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.

Legitimasjonsverktøyene er tilgjengelige i Python, PySpark, Scala og R-notatbøker. Eksemplene på denne siden bruker Python som hovedspråk, med Scala og R-ekvivalenter vist der det offentlige API-et støtter dem.

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 – Notatboken gir automatisk ut hemmelige verdier for å forhindre utilsiktet eksponering.
• 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()

notebookutils.credentials.help()

notebookutils.credentials.help()

Følgende tabell viser tilgjengelige metoder for legitimasjon:

Hent token

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

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

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

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}")

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 – Les og skriv tilgang til Lakehouse-artikler
  • MLExperiment.ReadWrite.All – Lese- og skrivetilgang til Machine Learning Experiment-objekter
  • MLModel.ReadWrite.All – Lese- og skrivetilgang til Machine Learning Model-elementer
  • Notebook.ReadWrite.All – Lese- og skrivetilgang til notatbøker
  • SparkJobDefinition.ReadWrite.All – Lese- og skrivetilgang til Spark Job Definition-elementer
  • Workspace.ReadWrite.All – Lese- og skrivetilgang til Workspace-elementer
  • Dataset.ReadWrite.All – Lese- og skrivetilgang til datasettelementer

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')

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

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}"

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 logg hemmelige verdier. Stol på den automatiske hemmelige redigeringen i notatbokens utdata. Unngå å skrive hemmeligheter til filer eller sende dem som notatbokparametere.
• 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

putSecret lagrer en hemmelighet i det spesifiserte Azure Key Vault. Hvis hemmeligheten allerede eksisterer, oppdateres verdien.

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

notebookutils.credentials.putSecret("https://<name>.vault.azure.net/", "secret name", "secret value")

Du må ha passende tillatelser (Set permission) på Azure Key Vault for å skrive hemmeligheter.

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')

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")

Relatert innhold

• NotebookUtils (tidligere MSSparkUtils) for Fabric