Integroi kolmannen osapuolen moottori OneLake-tietoturvaan (esikatselu)

Tässä artikkelissa kuvataan, miten kolmannen osapuolen moottorikehittäjät voivat integroitua OneLake-tietoturvaan ja hakea tietoja OneLakesta samalla kun noudatetaan rivitason tietoturvaa (RLS) ja saraketason turvallisuutta (CLS). Integraatio käyttää valtuutettua moottorimallia, jossa moottorisi lukee dataa suoraan OneLakesta ja valvoo turvallisuuspolitiikkoja omassa laskentakerroksessaan.

Yleiskatsaus

OneLake-turvallisuus määrittelee hienojakoiset käyttöoikeuksien hallintakäytännöt—mukaan lukien taulukko-, rivi- ja sarakketason tietoturvan—kun se on OneLakessa. Microsoft Fabricin moottorit, kuten Spark ja SQL-analytiikkapäätelaite, valvovat näitä käytäntöjä kyselyn aikana. Kuitenkin OneLaken turvallisuus takaa tarkkojen käyttöoikeuksien valvontapolitiikan valvonnan riippumatta siitä, miten dataan päästään käsiksi. Tämän seurauksena luvattomat ulkoiset pyynnöt lukea tiedostoja OneLakesta estetään, jotta tiedot eivät vuoda.

Valtuutettu moottorimalli ratkaisee tämän ongelman. Rekisteröit omistetun identiteetin (palvelupäähenkilö tai hallittu identiteetti), jolla on täysi lukuoikeus dataan ja joka voi myös lukea tietoturvametatietoja. Moottorisi käyttää tätä identiteettiä:

1. Lue OneLaken raakadatatiedostot.
2. Hae käyttäjän tehokkaat tietoturvakäytännöt kutsumalla Get authorized access -toimintoa päärajapintaan .
3. Sovella palautetut rivi- ja sarakkesuodattimet omaan kyselyn suorituskerrokseensa.
4. Palauta loppukäyttäjälle vain sallittu tieto.

Tämä lähestymistapa antaa moottorillesi täyden hallinnan kyselysuunnitteluun ja välimuistiin, samalla kun tietoturvavalvonta pysyy yhdenmukaisena Fabric-moottoreiden tarjoaman kanssa ja valtuutuksen hallinta siirtyy käyttäjän käsiin.

Edellytykset

Ennen kuin aloitat integraation, varmista, että sinulla on seuraavat ominaisuudet:

• Microsoft Entra -palvelupäähenkilö tai hallittu identiteetti, jota moottorisi käyttää OneLakeen. Vain Microsoft Entra -identiteetit ovat tuettuja.
• Työtilan jäsen (tai korkeampi) rooli moottorin identiteetille kohdetyötilassa. Tämä antaa henkilöllisyydelle tarvittavat oikeudet lukea OneLaken datatiedostoja ja tietoturvametatietoja.
• Fabric-kohde (lakehouse, peilattu tietokanta tai peilattu luettelo), jossa OneLake-turvallisuus on käytössä.
• OneLake-turvallisuusroolit on määritetty kyseiselle kohteelle kaikilla RLS- tai CLS-politiikoilla, joita haluat valvoa.
• Moottorin identiteetillä täytyy olla rajoittamaton lukuoikeus lukemiinsa taulukoihin. Jos RLS- tai CLS-käytännöt koskevat moottorin identiteettiä, API-kutsut palauttavat virheitä.

Arkkitehtuuri

Seuraava kaavio esittää valtuutetun moottorin integroinnin korkean tason valtuutuskulun.

┌──────────────┐       ┌──────────────────┐       ┌───────────┐
│  End user    │──1──▶│  3rd-party engine │──2──▶│  OneLake  │
│  (query)     │       │(service principal)│◀──3──│  (data +  │
│              │◀──6──│                   │──4──▶│  security)│
└──────────────┘       └──────────────────┘       └───────────┘

1. Loppukäyttäjä lähettää kyselyn kolmannen osapuolen moottorille.
2. Moottorin identiteetti autentikoituu OneLakeen ja lukee raakadatatiedostot (Delta parquet) OneLake-rajapintojen avulla.
3. OneLake palauttaa pyydetyt tiedot.
4. Moottori kutsuu principalAccess API:n, välittäen loppukäyttäjän Microsoft Entra -objekti-ID:n, saadakseen käyttäjän tehokkaan pääsyn.
5. Moottori soveltaa palautettuja pääsysuodattimia (taulukkokäyttö, RLS-predikaatit, CLS-sarakkeiden listat) omaan laskentakerrokseensa dataan.
6. Moottori palauttaa loppukäyttäjälle vain suodatetut, sallitut tulokset.

Vaihe 1: Aseta moottorin identiteetti

Moottorisi tarvitsee Microsoft Entra -identiteetin, jonka OneLake tunnistaa ja johon luottaa. Tämä identiteetti lukee datatiedostoja ja tietoturvametatietoja moottorisi puolesta.

1. Luo tai tunnista palvelupäähenkilö tai hallittu identiteetti Microsoft Entra ID:ssä moottorillesi. Lisätietoja on artikkelissa Sovelluksen ja palvelun päänimen objektit Microsoft Entra -tunnuksella.

2. Lisää identiteetti työtilan jäsenrooliin. Fabric-portaalissa mene työtilan asetuksiin ja lisää palvelupäähenkilö jäsenrooliin . Tämä antaa henkilöllisyyden:

   • Lue pääsy kaikkiin OneLaken tietotiedostoihin kyseisen työtilan kohteiden osalta.
   • Pääsy lukemaan OneLake-tietoturvaroolien metatietoja valtuutettujen moottorirajapintojen kautta.

   Lisätietoja työtilan rooleista löytyy kohdasta Roolit työtiloissa.

3. Varmista, että henkilöllisyydellä on rajoittamaton pääsy. Moottorin identiteetillä täytyy olla täysi lukuoikeus jokaiseen kyselyyn tauluun. Jos jokin OneLake-turvallisuusrooli asettaa RLS- tai CLS-rajoituksia moottorin identiteettiin, datan lukeminen ja API-kutsut epäonnistuvat. Paras käytäntö on olla lisäämättä moottorin identiteettiä mihinkään OneLake-tietoturvarooleihin, joissa on RLS- tai CLS-rajoitteita.

Vaihe 2: Lue tiedot OneLakesta

Kun moottorin identiteetti on konfiguroitu, moottorisi voi lukea datatiedostoja suoraan OneLakesta käyttäen standardeja Azure Data Lake Storage (ADLS) Gen2 -yhteensopivia rajapintoja.

OneLaken tiedot ovat saatavilla osoitteessa:

https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{itemId}/Tables/{schema}/{tableName}/

Moottorisi autentikoituu Microsoft Entra OAuth 2.0 -asiakastunnuksen kautta, joka on hankittu kantajatunnisteella. Käytä OneLake-resurssiskooppia https://storage.azure.com/.default , kun pyydät tokenia.

Esimerkki: Tunnista ja lue dataa (Python)

from azure.identity import ClientSecretCredential
from azure.storage.filedatalake import DataLakeServiceClient

tenant_id = "<your-tenant-id>"
client_id = "<your-service-principal-client-id>"
client_secret = "<your-service-principal-secret>"

credential = ClientSecretCredential(tenant_id, client_id, client_secret)

service_client = DataLakeServiceClient(
    account_url="https://onelake.dfs.fabric.microsoft.com",
    credential=credential
)

# Access a specific item in a workspace
file_system_client = service_client.get_file_system_client("<workspace-id>")
directory_client = file_system_client.get_directory_client("<item-id>/Tables/dbo/Customers")

# List and read Delta parquet files
for path in directory_client.get_paths():
    if path.name.endswith(".parquet"):
        file_client = file_system_client.get_file_client(path.name)
        downloaded = file_client.download_file()
        data = downloaded.readall()
        # Process the parquet data with your engine

Lisätietoja OneLake-rajapinnoista löytyy kohdasta OneLake-pääsy API-rajapintojen kanssa.

Vaihe 3: Hae käyttäjän tehokas pääsy

Raakadatan lukemisen jälkeen moottorisi täytyy selvittää, mitä kyselyn tekijä saa nähdä. Kutsu Get authorised access -palvelua päärajapintaa varten, jotta saat käyttäjän tehokkaan pääsyn kyseiseen kohteeseen.

Ohjelmointirajapinnan päätepiste

GET https://onelake.dfs.fabric.microsoft.com/v1.0/workspaces/{workspaceId}/artifacts/{artifactId}/securityPolicy/principalAccess

Pyynnön sisältö

{
  "aadObjectId": "<end-user-entra-object-id>",
  "inputPath": "Tables",
  "maxResults": 500 //optional, default is 500
}

Näytevaste (vain RLS)

{
  "identityETag": "3fc4dc476ded773e4cf43936190bf20fa9480a077b25edc0b4bbe247112542f6",
  "metadataETag": "\"eyJhciI6IlwiMHg4R...\"",
  "value": [
    {
      "path": "Tables/dbo/Customers",
      "access": ["Read"],
      "rows": "SELECT * FROM [dbo].[Customers] WHERE [customerId] = '123'",
      "effect": "Permit"
    },
    {
      "path": "Tables/dbo/Employees",
      "access": ["Read"],
      "rows": "SELECT * FROM [dbo].[Employees] WHERE [address] = '123'",
      "effect": "Permit"
    },
    {
      "path": "Tables/dbo/EmployeeTerritories",
      "access": ["Read"],
      "effect": "Permit"
    }
  ]
}

Näytevaste (RLS ja CLS)

Kun sarakkeen tason turvallisuus määritetään taulukossa, vastaus sisältää taulukon columns , joka listaa vain ne sarakkeet, joihin käyttäjä saa käyttää. Tässä taulukossa olemattomat sarakkeet ovat käyttäjältä piilotettuja.

{
  "identityETag": "79372bc169b00882d9abec3d404032131e96bc406e15c6766514723021e153eb",
  "metadataETag": "\"eyJhciI6IlwiMHg4R...\"",
  "value": [
    {
      "path": "Tables/dbo/Customers",
      "access": ["Read"],
      "columns": [
        {
          "name": "address",
          "columnEffect": "Permit",
          "columnAction": ["Read"]
        },
        {
          "name": "city",
          "columnEffect": "Permit",
          "columnAction": ["Read"]
        },
        {
          "name": "contactTitle",
          "columnEffect": "Permit",
          "columnAction": ["Read"]
        },
        {
          "name": "country",
          "columnEffect": "Permit",
          "columnAction": ["Read"]
        },
        {
          "name": "fax",
          "columnEffect": "Permit",
          "columnAction": ["Read"]
        },
        {
          "name": "phone",
          "columnEffect": "Permit",
          "columnAction": ["Read"]
        },
        {
          "name": "postalCode",
          "columnEffect": "Permit",
          "columnAction": ["Read"]
        },
        {
          "name": "region",
          "columnEffect": "Permit",
          "columnAction": ["Read"]
        }
      ],
      "rows": "SELECT * FROM [dbo].[Customers] WHERE [customerID] = 'ALFKI'",
      "effect": "Permit"
    },
    {
      "path": "Tables/dbo/Employees",
      "access": ["Read"],
      "rows": "SELECT * FROM [dbo].[Employees] WHERE [address] = '123'",
      "effect": "Permit"
    }
  ]
}

Vastauksen ymmärtäminen

Vastaus sisältää taulukon objekteja PrincipalAccessEntry , joista jokainen edustaa taulua, johon käyttäjällä on pääsy. Taulut, joita ei ole vastauksessa, eivät ole käyttäjän käytettävissä.

ETags välimuistiin

Vastaus sisältää kaksi ETag-arvoa, jotka mahdollistavat tehokkaan välimuistin:

• identityETag: Edustaa käyttäjän identiteetin ja ryhmäjäsenyyksien nykytilaa. Tallenna käyttäjän käyttöoikeustulos välimuistiin ja käytä sitä uudelleen, kunnes tämä ETag muuttuu.
• metadataETag: Edustaa tuotteen turvallisuuskonfiguraatioiden nykytilaa. Välimuisti roolien metatiedot ja käytä niitä uudelleen, kunnes tämä ETag muuttuu.

Käytä näitä ETag-tiedostoja pyyntöotsikon If-None-Match kanssa välttääksesi muuttumattoman datan uudelleenhakeen. Tämä parantaa suorituskykyä monen käyttäjän välimuistissa.

Esimerkki: Fetch effective access (Python)

import requests

# Get a token for the OneLake DFS endpoint
token = credential.get_token("https://storage.azure.com/.default").token

workspace_id = "<workspace-id>"
artifact_id = "<artifact-id>"
user_object_id = "<end-user-entra-object-id>"

url = (
    f"https://onelake.dfs.fabric.microsoft.com/v1.0/"
    f"workspaces/{workspace_id}/artifacts/{artifact_id}/"
    f"securityPolicy/principalAccess"
)

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

body = {
    "aadObjectId": user_object_id,
    "inputPath": "Tables"
}

response = requests.get(url, headers=headers, json=body)
access_data = response.json()

# The response contains the user's effective access
for entry in access_data["value"]:
    print(f"Table: {entry['path']}, Access: {entry['access']}")
    if "columns" in entry:
        col_names = [col["name"] for col in entry["columns"]]
        print(f"  CLS permitted columns: {col_names}")
    if "rows" in entry:
        print(f"  RLS filter: {entry['rows']}")

Vaihe 4: Käytä turvasuodattimia

Kun käyttäjä on saanut tehokkaan pääsyn, moottorisi on sovellettava tietoturvapolitiikkoja dataan ennen tulosten palauttamista. Tämä vaihe on ratkaisevan tärkeä—moottorisi vastaa politiikkojen oikeasta valvonnasta.

Taulukkotason suodatus

Palauta principalAccess tiedot vain tauluista, jotka näkyvät vastauksessa. Jos taulukkoa ei ole listattu, käyttäjällä ei ole siihen pääsyä eikä tietoja tulisi palauttaa.

# Build a set of accessible tables for the user
accessible_tables = {entry["path"] for entry in access_data["value"]}

# Before returning query results, verify the table is accessible
def is_table_accessible(table_path: str) -> bool:
    return table_path in accessible_tables

Rivitason turvallisuussuodatus

Kun rows kenttä on läsnä pääsymerkinnässä, moottorisi täytyy jäsentää T-SQL-predikaatti ja soveltaa sitä suodattimena taulukon dataan. Arvo rows on lause SELECT , jossa on WHERE lause, joka määrittelee, mitkä rivit käyttäjä voi nähdä.

Esimerkiksi seuraava RLS-suodatin:

SELECT * FROM [dbo].[Customers] WHERE [customerId] = '123' UNION SELECT * FROM [dbo].[Customers] WHERE [customerID] = 'ALFKI'

Moottorisi pitäisi poimia predikaatit ja soveltaa niitä datan suodattamiseen:

import sqlparse

def extract_rls_predicates(rls_expression: str) -> list:
    """
    Parse the RLS T-SQL expression and extract WHERE clause predicates.
    The expression may contain UNION of multiple SELECT statements.
    """
    predicates = []
    statements = rls_expression.split(" UNION ")
    for stmt in statements:
        parsed = sqlparse.parse(stmt)[0]
        where_seen = False
        where_clause = []
        for token in parsed.tokens:
            if where_seen:
                where_clause.append(str(token).strip())
            if token.ttype is sqlparse.tokens.Keyword and token.value.upper() == "WHERE":
                where_seen = True
        if where_clause:
            predicates.append(" ".join(where_clause))
    return predicates


def apply_rls_filter(dataframe, access_entry: dict):
    """Apply RLS filtering to a dataframe based on the access entry."""
    if "rows" not in access_entry:
        return dataframe  # No RLS, return all rows

    predicates = extract_rls_predicates(access_entry["rows"])
    # Combine predicates with OR (UNION semantic)
    combined_filter = " OR ".join(f"({p})" for p in predicates)
    return dataframe.filter(combined_filter)

Sarakketason turvallisuussuodatus

Kun CLS on konfiguroitu taulukossa, vastaus principalAccess sisältää taulukon columns , joka nimenomaisesti listaa käyttäjälle sallitut sarakkeet. Jokainen sarakeobjekti sisältää:

Jos columns kenttä puuttuu pääsymerkinnästä, CLS:ää ei koske ja kaikki taulukon sarakkeet ovat sallittuja. Jos kenttä columnson läsnä, moottorisi palauttaa vain luetellut sarakkeet.

def get_permitted_columns(access_entry: dict) -> list | None:
    """
    Return the list of permitted column names for a table.
    Returns None if no CLS applies (all columns are permitted).
    """
    if "columns" not in access_entry:
        return None  # No CLS, all columns are permitted

    return [
        col["name"]
        for col in access_entry["columns"]
        if col.get("columnEffect") == "Permit"
        and "Read" in col.get("columnAction", [])
    ]


def apply_cls_filter(dataframe, access_entry: dict):
    """Apply CLS filtering to a dataframe based on the access entry."""
    permitted_columns = get_permitted_columns(access_entry)
    if permitted_columns is None:
        return dataframe  # No CLS, return all columns

    # Only keep columns that are in the permitted list
    return dataframe.select(permitted_columns)

Käsittelytaulukot ilman pääsyä

Jos käyttäjä kysyy taulua, joka ei näy vastauksessa principalAccess , moottorisi joutuu evätä pääsyn. Älä palaa suodattamattomien tietojen palauttamiseen.

def query_table(table_path: str, user_access: dict):
    """Query a table with OneLake security enforcement."""
    # Find the user's access entry for this table
    entry = next(
        (e for e in user_access["value"] if e["path"] == table_path),
        None
    )

    if entry is None:
        raise PermissionError(
            f"Access denied: user doesn't have permission to access {table_path}"
        )

    # Read the data from OneLake
    data = read_table_from_onelake(table_path)

    # Apply column-level security
    data = apply_cls_filter(data, entry)

    # Apply row-level security
    data = apply_rls_filter(data, entry)

    return data

Vaihe 5: Hoida välimuisti ja muutosten tunnistus

Tuotantotason integraatioissa, erityisesti moottoreissa, joissa on monen käyttäjän datavälimuistit, sinun täytyy käsitellä muutoksia tietoturvapolitiikoihin ja käyttäjäryhmien jäsenyyksiin.

Välimuistin turvallisuusmetatiedot

Käytä vastauksen identityETagprincipalAccess ja-arvoja metadataETag määrittääksesi, milloin välimuistissa oleva tietoturvatieto on vanhentunutta:

• identityETag: Muuttuu, kun käyttäjän ryhmäjäsenyydet tai identiteettiominaisuudet päivitetään. Välimuistita käyttäjän tehokas käyttöoikeus, joka on näppäimistöllä (userId, identityETag).
• metadataETag: Muuttuu, kun OneLake-turvallisuusroolit tai -käytännöt päivitetään. Välimuistiroolien määritelmät on asetettu .(artifactId, metadataETag)

Kyselyt muutoksen varalta

Tarkista API principalAccess :sta säännöllisesti muutoksia. API tulisi tarkistaa ennen kyselyn suoritusta, jotta varmistetaan, ettei mikään ole muuttunut, sen sijaan että tuloksia tarjottaisiin suoraan välimuistista. Käytä aiemmin vastaanotettua If-None-Match otsikkoa ETag kaistanleveyden minimoimiseksi:

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "If-None-Match": f'"{cached_etag}"'
}

response = requests.get(url, headers=headers, json=body)

if response.status_code == 304:
    # Security hasn't changed, use cached data
    pass
elif response.status_code == 200:
    # Security has changed, update cache
    new_access_data = response.json()
    update_cache(user_id, new_access_data)

Viivettä koskevia huomioita

• Muutokset OneLake-turvallisuusroolimäärittelyihin vievät noin 5 minuuttia levitettäväksi.
• Microsoft Entra ID:n käyttäjäryhmäjäsenyyden muutokset heijastuvat OneLakessa noin tunnissa .
• Joillakin Fabric-moottoreilla on oma välimuistikerros, joten se saattaa vaatia lisäaikaa.

Suunnittele äänestysväliaikasi ja välimuisti TTL sen mukaan. Suositeltu lähestymistapa on kysely viiden minuutin välein tietoturvametatietojen muutoksista ja päivittää käyttäjäkohtainen pääsy jokaisessa kyselyssä tai lyhyemmällä ajalla.

Vaihe 6: Käsittele sivuttamista

API principalAccess tukee sivuttamista alkioille, joissa on useita taulukoita. Kun vastaus sisältää enemmän merkintöjä kuin maxResults, vastaus sisältää .continuationToken

all_entries = []
continuation_token = None

while True:
    body = {
        "aadObjectId": user_object_id,
        "inputPath": "Tables",
        "maxResults": 500
    }
    if continuation_token:
        body["continuationToken"] = continuation_token

    response = requests.get(url, headers=headers, json=body)
    data = response.json()
    all_entries.extend(data["value"])

    # Check for continuation token in response
    continuation_token = data.get("continuationToken")
    if not continuation_token:
        break

Virheenkäsittely

Käsittele seuraavat virhetilanteet integraatiossasi:

Suojauksen parhaat käytännöt

Noudata näitä parhaita käytäntöjä varmistaaksesi turvallisen integraation:

• Suojaa moottorin identiteettitiedot. Palvelupäämiehellä on kohonnut pääsy dataan OneLakessa. Tallenna tunnistetiedot turvallisesti palveluilla, kuten Azure Key Vault.
• Älä paljasta raakadataa loppukäyttäjille. Käytä aina API:n palauttamia turvasuodattimia ennen kuin palautat principalAccess mitään tietoa. Valvonnan ohittaminen on turvallisuusrikkomus.
• Tarkista RLS-predikaatit huolellisesti. Jäsennä ja sovella T-SQL-lauseketta WHERE tarkasti. Virheellinen jäsentäminen voi johtaa datavuotoon. Jos jäsennysvirheitä ilmenee tai epätarkka syntaksikartoitus, epäonnistu kysely RLS-jäsennysvirheellä sen sijaan, että näyttäisit käyttäjälle osittaisia tai turvattomia tuloksia.
• Käsittele puuttuvat taulukot pääsyn evättynä. Jos API-vastauksessa ei ole taulukkoa, käyttäjällä ei ole siihen pääsyä. Älä koskaan palaa suodattamattomiin tietoihin, OneLake-tietoturva käyttää aina oletuksena kieltämistä.
• Auditointioikeudet. Kirjaa, mitkä käyttäjät käyttävät mitäkin taulua ja mitä turvallisuuspolitiikkoja sovellettiin vaatimustenmukaisuuden ja vianetsinnän varmistamiseksi.
• Kysely turvallisuusmuutoksista. Käytä ETagsia muutosten tunnistamiseen ja välimuistissa olevien käytäntöjen nopeaan päivittämiseen.

Rajoitukset

• API principalAccess on esikatseluvaiheessa ja voi muuttua palautteen perusteella.
• Nykyään tuetaan Read vain pääsyn tyyppi ja Permit vaikutus.
• Moottorin identiteetillä täytyy olla rajoittamaton juuritason pääsy. Jos RLS tai CLS koskee moottorin identiteettiä, API-kutsut epäonnistuvat.
• RLS-predikaatit käyttävät T-SQL-syntaksia. Moottorisi vastaa predikaattien oikeasta jäsentämisestä ja soveltamisesta.
• Turvallisuuspolitiikan muutosten leviäminen kestää noin 5 minuuttia. Käyttäjäryhmän jäsenvaihdot kestävät noin tunnin.

Liittyvä sisältö

• Hanki valtuutettu pääsy pääasialliseen API-viittaukseen
• OneLake-tietoturvaintegraatioiden yleiskatsaus
• OneLake-tietoturvaintegraatioiden viite
• OneLake Security access control -malli
• Rivitason turvallisuus OneLakessa
• Pylvästason turvallisuus OneLakessa
• Aloita OneLake-turvallisuuden parissa