NotebookUtils credentials-værktøjer til Fabric

Du kan bruge legitimationsværktøjerne til at få adgangstokens og administrere hemmeligheder i Azure Key Vault. Modulet notebookutils.credentials integreres med Microsoft Entra ID til tokenindsamling og Azure Key Vault til hemmelig styring, så du sikkert kan forbinde til Azure-ressourcer uden at eksponere legitimationsoplysninger i koden.

Du kan bruge legitimationsværktøjerne i Python-notebooks og Fabric Spark-notebooks. I Fabric Spark-notebooks kan du bruge PySpark, Scala eller R. Metodetilgængeligheden varierer afhængigt af notebook-runtime og API. For eksempel fungerer kun putSecret i Python-notebooks, som bruger Python runtime. Spark-notebooks understøtter det ikke, selv når de kører Python-kode med PySpark. Spark-notebooks, der bruger Scala eller R, understøtter det heller ikke.

Følgende eksempler bruger Python som det primære sprog. Scala- og R-ækvivalenter opstår, hvor notebook-runtime og public API understøtter metoden.

Vigtigt!

Kod aldrig hemmeligheder eller legitimationsoplysninger direkte i notesbogskoden. Brug altid Azure Key Vault til at gemme følsomme værdier og hente dem under kørsel med notebookutils.credentials.getSecret.

Begrænsninger og sikkerhed

Før du bruger legitimationsværktøjer, skal du være opmærksom på disse begrænsninger:

  • Tokenudløb – Tokens udløber efter en periode. For langvarige operationer implementeres opdateringslogik for at anmode om et nyt token før udløb.
  • Service principal scope-begrænsninger – Når tokens for pbi publikum kører under en service principal, har de begrænsede scopes sammenlignet med brugeridentiteten.
  • MSAL for fuldt omfang – Hvis du har brug for hele Fabric-serviceomfanget under en serviceprincipal, brug MSAL-autentificering i stedet for getToken.
  • Hemmelig redigering – Notebook-output forsøger at redigere den oprindelige hemmelige værdi, når koden udskrives eller vises direkte. Denne bedste indsats beskytter utilsigtet afsløring, også under skærmdeling. Det er ikke en sikkerhedsgrænse. Efter hentning modtager autoriseret notesbogskode klartekst og kan behandle, transformere eller offentliggøre det hemmelige eller hemmelige indhold.
  • Key Vault-tilladelser – Du skal have passende tilladelser (Get for reading, Set for writing) på Azure Key Vault for at få adgang til eller gemme hemmeligheder.
  • Publikumsændringer – Token-publikumsomfang kan udvikle sig over tid. Verificér de nuværende scopes i dokumentationen.

Kør følgende kommando for at få en oversigt over de tilgængelige metoder:

notebookutils.credentials.help()

Følgende tabel viser de tilgængelige metoder til legitimationsoplysninger:

Metode Signatur Beskrivelse
getToken getToken(audience: String): String Returnerer et Microsoft Entra-token for den angivne målgruppe.
getSecret getSecret(akvName: String, secret: String): String Returnerer værdien af en hemmelighed fra det specificerede Azure Key Vault.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Gemmer en hemmelighed i det specificerede Azure Key Vault. Denne metode fungerer kun i notesbøger, der bruger Python-runtime. Spark-notebooks understøtter det ikke, selv når de kører Python-kode med PySpark. Spark-notebooks, der bruger Scala eller R, understøtter det heller ikke.
isValidToken isValidToken(token: String): Boolean Tjekker, om den givne token er gyldig og ikke udløbet. Denne metode er ikke tilgængelig i det offentlige Scala API.

Hent token

getToken returnerer et Microsoft Entra-token for et givent publikum. Følgende tabel viser de aktuelt tilgængelige målgruppenøgler:

Målgruppenøgle Ressource Brugsscenarie
storage Azure Storage Få adgang til ADLS Gen2 og blob-lagring
pbi Power BI Kald Power BI og Fabric REST API'er
keyvault Azure Key Vault Hent nøglehvælvingens hemmeligheder
kusto Synapse RTA KQL DB Connect to Azure Data Explorer

Kør følgende kommando for at hente tokenet:

notebookutils.credentials.getToken('audience Key')

Eksempler på tokenbrug

Du kan bruge det returnerede token til at autentificere mod forskellige 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')

Brug tokens med Azure SDK

Stofnotesbøger understøtter DefaultAzureCredential ikke direkte. Du kan bruge en brugerdefineret credential-klasse som en løsning til at 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 udløber efter en periode. Hvis din notebook kører lange operationer, implementer opdateringslogik for at anmode om et nyt token, før det nuværende udløber.

Overvejelser

  • Token-scopes med pbi en målgruppe kan ændre sig over tid.

  • Når du kalder notebookutils.credentials.getToken("pbi"), har det returnerede token begrænset omfang, hvis notebooken kører under en service principal. Tokenet har ikke hele Fabric-service-omfanget. Hvis notebooken kører under brugeridentiteten, har tokenet stadig hele Fabric-serviceomfanget, men dette kan ændre sig med sikkerhedsforbedringer. For at sikre, at tokenet har hele Fabric-serviceomfanget, brug MSAL-autentificering i stedet for API'et notebookutils.credentials.getToken . Du kan finde flere oplysninger under Godkend med Microsoft Entra ID.

  • Følgende scopes er tilgængelige, når du ringer notebookutils.credentials.getToken med audience-nøglen pbi under service principal-identiteten:

    • Lakehouse.ReadWrite.All – Læs og skriv adgang til søhusartikler
    • MLExperiment.ReadWrite.All – Læse- og skriveadgang til eksperimentopgaver
    • MLModel.ReadWrite.All – Læse- og skriveadgang til ML-modelelementer
    • Notebook.ReadWrite.All – Læse- og skriveadgang til notesbogselementer
    • SparkJobDefinition.ReadWrite.All – Læse- og skriveadgang til Spark-jobdefinitionselementer
    • Workspace.ReadWrite.All – Læse- og skriveadgang til arbejdsområder
    • Dataset.ReadWrite.All – Læse- og skriveadgang til semantiske modelelementer

Tips

Hvis du har brug for adgang til yderligere Fabric-tjenester eller bredere tilladelser under en serviceprincipal, så brug MSAL for Python til at autentificere direkte med hele Fabric-serviceomfanget i stedet for at stole på getToken("pbi").

Bliv hemmelig

getSecret returnerer en Azure Key Vault-hemmelighed for et givent Azure Key Vault-endpoint og hemmeligt navn. Opkaldet bruger dine nuværende brugeroplysninger til at autentificere mod Key Vault.

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

Du kan hente flere hemmeligheder for at bygge forbindelsesstrenge 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}"

Vigtigt!

Efter vellykket hentning modtager autoriseret notebook-kode den hemmelige værdi som klartekst. Notebook-output forsøger at redigere den oprindelige hemmelige værdi, når koden udskrives eller viser den direkte.

Denne bedste indsats reducerer utilsigtet afsløring i notebooks output, også under skærmdeling. Det er ikke en sikkerhedsgrænse og forhindrer ikke behandling, transformation eller offentliggørelse af hemmeligt afledt indhold.

Brug den fuldt kvalificerede Key Vault URL i formatet https://<vault-name>.vault.azure.net/. Du skal have de nødvendige tilladelser for at få adgang til Key Vault og de enkelte hemmeligheder.

Bedste praksis for sikkerhed

Følg disse anbefalinger, når du arbejder med kvalifikationer i Fabric-notesbøger:

  • Gem alle følsomme værdier i Azure Key Vault. Indlejr aldrig legitimationsoplysninger, forbindelsesstrenge eller API-nøgler direkte i notesbogens kode.
  • Afslør ikke hemmelige værdier. Print eller log ikke hemmeligheder, skriv dem ikke til filer eller send dem som notesbogsparametre. Outputredigering forsøger at beskytte den oprindelige værdi i direkte notesbogsoutput. Det forhindrer ikke offentliggørelse af hemmeligt afledt indhold.
  • Brug den korrekte målgruppe-nøgle. Match målgruppenøglen med den målrettede Azure-ressource, så tokenet kun har de nødvendige tilladelser.
  • Forstå identitetskonteksten. Vær opmærksom på, om din notebook kører under brugeridentitet eller en serviceprincipal, fordi de tilgængelige token-omfang kan variere. Testautentificering både i interaktive og pipeline-sammenhænge.
  • Håndter token-udløb. Tokens udløber. For langvarige operationer implementeres opdateringslogik for at anmode om et nyt token, før det nuværende udløber.
  • Begræns adgangen til Key Vault. Giv kun de nødvendige minimumstilladelser til din Key Vault. Audit hemmelig adgang via Azure Key Vault diagnostiske logfiler.
  • Brug administrerede identiteter, når det er muligt. Administrerede identiteter reducerer behovet for manuel at administrere legitimationsoplysninger og giver en mere sikker autentificeringsflow.

Sæt hemmelighed

putSecretgemmer eller opdaterer en hemmelighed i det specificerede Azure Key Vault. Det virker kun i notebooks, der bruger Python-runtime.

Vigtigt!

Spark-notebooks understøtter putSecretikke, selv når de kører Python-kode med PySpark. Spark-notebooks, der bruger Scala eller R, understøtter det heller ikke. Brug en Python-notesbog, som bruger 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 at skrive hemmeligheder skal du bruge passende tilladelser (Set tilladelse) på Azure Key Vault. Kør følgende eksempel kun i en notesbog, der bruger Python-runtime. Lad være med at skrive det i en Fabric Spark-notesbog.

# 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

Brug isValidToken den til at tjekke, om et token er gyldigt og ikke udløbet, før du kalder 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')

Relateret indhold

  • Sidst opdateret den