NotebookUtils legitimasjonsverktøy for Fabric

Du kan bruke legitimasjonsverktøyene for å få tilgang til tokens og administrere hemmeligheter i Azure Key Vault. Modulen notebookutils.credentials integreres med Microsoft Entra ID for tokeninnhenting og Azure Key Vault for hemmelig administrasjon, slik at du trygt kan koble til Azure-ressurser uten å eksponere legitimasjon i koden.

Du kan bruke legitimasjonsverktøyene i Python-notatbøker og Fabric Spark-notatbøker. I Fabric Spark-notatbøker kan du bruke PySpark, Scala eller R. Metodetilgjengeligheten varierer mellom notatbokens kjøretid og API. For eksempel fungerer det putSecret kun i Python-notatbøker, som bruker Python-runtime. Spark-notatbøker støtter det ikke, selv når de kjører Python-kode med PySpark. Spark-notatbøker som bruker Scala eller R støtter det heller ikke.

Følgende eksempler bruker Python som hovedspråk. Scala- og R-ekvivalenter dukker opp der notebook-kjøretiden og det offentlige API-et støtter metoden.

Viktig!

Aldri hardkode hemmeligheter eller legitimasjoner direkte i notatbokkoden. Bruk alltid Azure Key Vault for å lagre sensitive verdier og hente dem under kjøring med notebookutils.credentials.getSecret.

Begrensninger og sikkerhet

Før du bruker verktøy for legitimasjon, bør du være oppmerksom på disse begrensningene:

  • Tokenutløp – Tokens utløper etter en periode. For langvarige operasjoner, implementer oppdateringslogikk for å be om en ny token før utløp.
  • Begrensninger for tjenesteprinsippets omfang – Når man kjører under en tjenesteprinsipp, har tokens for målgruppen pbi begrensede omfang sammenlignet med brukeridentiteten.
  • MSAL for full omfang – Hvis du trenger hele Fabric-tjenesteomfanget under en tjenesteprinsipp, bruk MSAL-autentisering i stedet for getToken.
  • Hemmelig redigering – Notatbokens utdata forsøker å sensurere den opprinnelige hemmelige verdien når koden skrives ut eller vises direkte. Denne beste innsatsen reduserer utilsiktet avsløring, også under skjermdeling. Det er ikke en sikkerhetsgrense. Etter henting mottar autorisert notatbokkode klartekst og kan behandle, transformere eller avsløre det hemmelige eller hemmelige innholdet.
  • Key Vault-tillatelser – Du må ha riktige tillatelser (Get for reading, Set for writing) på Azure Key Vault for å få tilgang til eller lagre hemmeligheter.
  • Endringer i publikum – Token-publikumsområder kan utvikle seg over tid. Verifiser nåværende skalaer i dokumentasjonen.

Kjør følgende kommando for å få en oversikt over de tilgjengelige metodene:

notebookutils.credentials.help()

Følgende tabell viser tilgjengelige metoder for legitimasjon:

Metode Signatur Beskrivelse
getToken getToken(audience: String): String Returnerer et Microsoft Entra-token for den spesifiserte målgruppen.
getSecret getSecret(akvName: String, secret: String): String Returnerer verdien av en hemmelighet fra det spesifiserte Azure Key Vault.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Lagrer en hemmelighet i det spesifiserte Azure Key Vault. Denne metoden fungerer kun i notatbøker som bruker Python-runtime. Spark-notatbøker støtter det ikke, selv når de kjører Python-kode med PySpark. Spark-notatbøker som bruker Scala eller R støtter det heller ikke.
isValidToken isValidToken(token: String): Boolean Sjekker om tokenet er gyldig og ikke utløpt. Denne metoden er ikke tilgjengelig i det offentlige Scala API-et.

Hent token

getToken returnerer en Microsoft Entra-token for et gitt publikum. Tabellen nedenfor viser de tilgjengelige publikumsnøklene:

Målgruppenøkkel Ressurs Brukstilfelle
storage Azure Storage Få tilgang til ADLS Gen2 og Blob Storage
pbi Power BI Kall Power BI og Fabric REST API-er
keyvault Azure Key Vault Hent Key Vault-hemmeligheter
kusto Synapse RTA KQL DB Connect to Azure Data Explorer

Kjør følgende kommando for å hente tokenet:

notebookutils.credentials.getToken('audience Key')

Eksempler på tokenbruk

Du kan bruke det returnerte tokenet til å autentisere mot ulike Azure-tjenester.

Azure Storage

storage_token = notebookutils.credentials.getToken('storage')

Power BI og Fabric REST API-er

import requests

pbi_token = notebookutils.credentials.getToken('pbi')

headers = {
    'Authorization': f'Bearer {pbi_token}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.powerbi.com/v1.0/myorg/datasets',
    headers=headers
)

if response.status_code == 200:
    datasets = response.json()
    print(f"Found {len(datasets['value'])} datasets")

Azure Data Explorer (Kusto)

kusto_token = notebookutils.credentials.getToken('kusto')

Azure Key Vault

keyvault_token = notebookutils.credentials.getToken('keyvault')

Bruk tokens med Azure SDK

Stoffnotatbøker støtter DefaultAzureCredential det ikke direkte. Du kan bruke en egendefinert credential-klasse som en løsning for å sende NotebookUtils-tokens til Azure SDK-klienter.

from azure.core.credentials import AccessToken, TokenCredential
import jwt

class NotebookUtilsCredential(TokenCredential):
    """Custom credential that uses notebookutils tokens for Azure SDK."""

    def __init__(self, audience="storage"):
        self.audience = audience

    def get_token(self, *scopes, claims=None, tenant_id=None, **kwargs):
        token = notebookutils.credentials.getToken(self.audience)

        # Decode token to get expiration time
        token_json = jwt.decode(
            token, algorithms="RS256",
            options={"verify_signature": False}
        )

        return AccessToken(token, int(token_json.get("exp", 0)))

# Example: use with Azure Blob Storage
from azure.storage.blob import BlobServiceClient

account_url = "https://mystorageaccount.blob.core.windows.net"
credential = NotebookUtilsCredential(audience="storage")
blob_client = BlobServiceClient(account_url=account_url, credential=credential)

for container in blob_client.list_containers():
    print(f"Container: {container.name}")

Tips

Tokens utløper etter en viss tid. Hvis notatboken din kjører lange operasjoner, implementer oppdateringslogikk for å be om en ny token før den nåværende utløper.

Vurderinger

  • Token-omfang med pbi en målgruppe kan endre seg over tid.

  • Når du kaller notebookutils.credentials.getToken("pbi"), har det returnerte tokenet begrenset omfang hvis notatboken kjører under en tjenesteprinsipp. Tokenet har ikke hele Fabric-tjenesteomfanget. Hvis notatboken kjører under brukeridentiteten, har tokenet fortsatt hele Fabric-tjenesteomfanget, men dette kan endre seg med sikkerhetsforbedringer. For å sikre at tokenet har hele Fabric-tjenesteomfanget, bruk MSAL-autentisering i stedet for API-et notebookutils.credentials.getToken . Hvis du vil ha mer informasjon, kan du se Godkjenne med Microsoft Entra ID.

  • Følgende omfang er tilgjengelige når du ringer notebookutils.credentials.getToken med publikumsnøkkelen pbi under tjenestehovedidentiteten:

    • Lakehouse.ReadWrite.All – Lese og skrive tilgang til innsjøhusartikler
    • MLExperiment.ReadWrite.All – Lese- og skrivetilgang til eksperimentoppgaver
    • MLModel.ReadWrite.All – Lese- og skrivetilgang til ML-modellelementer
    • Notebook.ReadWrite.All – Lese- og skrivetilgang til notatbøker
    • SparkJobDefinition.ReadWrite.All – Lese- og skrivetilgang til Spark-jobbdefinisjonselementer
    • Workspace.ReadWrite.All – Lese- og skrivetilgang til arbeidsområder
    • Dataset.ReadWrite.All – Lese- og skrivetilgang til semantiske modellelementer

Tips

Hvis du trenger tilgang til flere Fabric-tjenester eller bredere tillatelser under en tjenesteprinsipp, bruk MSAL for Python for å autentisere direkte med hele Fabric-tjenesteomfanget i stedet for å stole på getToken("pbi").

Bli hemmelig

getSecret returnerer en Azure Key Vault-hemmelighet for et gitt Azure Key Vault-endepunkt og hemmelig navn. Samtalen bruker dine nåværende brukerlegitimasjoner for å autentisere mot Key Vault.

notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name')

Du kan hente flere hemmeligheter for å bygge tilkoblingsstrenger eller konfigurere tjenester:

vault_url = "https://myvault.vault.azure.net/"

db_host = notebookutils.credentials.getSecret(vault_url, "db-host")
db_user = notebookutils.credentials.getSecret(vault_url, "db-user")
db_password = notebookutils.credentials.getSecret(vault_url, "db-password")

connection_string = f"Server={db_host};User={db_user};Password={db_password}"

Viktig!

Etter vellykket henting mottar autorisert notatbokkode den hemmelige verdien som klartekst. Notatbokens utdata forsøker å redigere den opprinnelige hemmelige verdien når koden skrives ut eller vises direkte.

Denne beste innsatsen reduserer utilsiktet avsløring i notatbokens utdata, også under skjermdeling. Det er ikke en sikkerhetsgrense og hindrer ikke behandling, transformasjon eller offentliggjøring av hemmelig avledet innhold.

Bruk den fullt kvalifiserte Key Vault-URL-en i formatet https://<vault-name>.vault.azure.net/. Du må ha riktige tillatelser for å få tilgang til Key Vault og de individuelle hemmelighetene.

Anbefalte fremgangsmåter for sikkerhet

Følg disse anbefalingene når du jobber med kvalifikasjoner i Fabric-notatbøker:

  • Lagre alle sensitive verdier i Azure Key Vault. Aldri legg inn legitimasjon, tilkoblingsstrenger eller API-nøkler direkte i notatbokkoden.
  • Ikke avslør hemmelige verdier. Ikke skriv ut eller logg hemmeligheter, skriv dem til filer, eller send dem som notatbokparametere. Utdataredigering forsøker å beskytte den opprinnelige verdien i direkte notatbokutdata. Den forhindrer ikke offentliggjøring av hemmelig avledet innhold.
  • Bruk riktig målgruppe-nøkkel. Match målgruppenøkkelen med den målrettede Azure-ressursen slik at tokenet kun har de tillatelsene det trenger.
  • Forstå identitetskonteksten. Vær klar over om notatboken din kjører under brukeridentitet eller en tjenesteprincipal, fordi de tilgjengelige token-omfangene kan variere. Testautentisering i både interaktive og pipeline-kontekster.
  • Håndter token-utløp. Tokens utløper. For langvarige operasjoner, implementer oppdateringslogikk for å be om et nytt token før det nåværende utløper.
  • Begrens tilgang til Key Vault. Gi kun de nødvendige nødvendige tillatelsene til ditt Key Vault. Revider hemmelig tilgang gjennom Azure Key Vault diagnostiske logger.
  • Bruk administrerte identiteter når det er mulig. Administrerte identiteter reduserer behovet for å administrere legitimasjon manuelt og gir en sikrere autentiseringsflyt.

Sett det hemmelig

putSecretlagrer eller oppdaterer en hemmelighet i den spesifiserte Azure Key Vault. Det fungerer bare i notatbøker som bruker Python-runtime.

Viktig!

Spark-notatbøker støtter putSecretikke, selv når de kjører Python-kode med PySpark. Spark-notatbøker som bruker Scala eller R støtter det heller ikke. Bruk en Python-notatbok, som bruker Python-runtime.

# Run only in a notebook that uses the Python runtime.
notebookutils.credentials.putSecret(
    'https://<name>.vault.azure.net/',
    'secret name',
    'secret value'
)

For å skrive hemmeligheter trenger du passende tillatelser (Set permission) på Azure Key Vault. Kjør følgende eksempel kun i en notatbok som bruker Python-runtime. Ikke kjør det i en Fabric Spark-notatbok.

# Python runtime only. Fabric Spark notebooks don't support putSecret.
vault_url = "https://myvault.vault.azure.net/"

notebookutils.credentials.putSecret(vault_url, "api-key", "my-secret-api-key-value")

Valider token

Bruk isValidToken den for å sjekke om et token er gyldig og ikke utløpt før du kaller et API med det.

token = notebookutils.credentials.getToken('storage')
is_valid = notebookutils.credentials.isValidToken(token)

if is_valid:
    print("Token is valid")
else:
    print("Token is expired or invalid, requesting a new one")
    token = notebookutils.credentials.getToken('storage')

Relatert innhold

  • Last updated on