Del via

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.

Credentials-værktøjerne er tilgængelige i Python, PySpark, Scala og R-notebooks. Eksemplerne på denne side bruger Python som primært sprog, hvor Scala og R-ækvivalenter vises, hvor det offentlige API understøtter dem.

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 – Notesbogen udskriver automatisk hemmelige værdier for at forhindre utilsigtet eksponering.
  • 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 er ikke tilgængelig i det offentlige Scala API.
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 Lakehouse-artikler
    • MLExperiment.ReadWrite.All – Læse- og skriveadgang til Machine Learning Experiment-elementer
    • MLModel.ReadWrite.All – Læse- og skriveadgang til Machine Learning Model-elementer
    • Notebook.ReadWrite.All – Læse- og skriveadgang til notesbogselementer
    • SparkJobDefinition.ReadWrite.All – Læse- og skriveadgang til Spark Job Definition-elementer
    • Workspace.ReadWrite.All – Læse- og skriveadgang til arbejdsområdeelementer
    • Dataset.ReadWrite.All – Læse- og skriveadgang til datasætelementer

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

Bemærkning

Notebooks output redigerer automatisk hemmelige værdier for sikkerhedens skyld. Hvis du udskriver eller viser en hentet hemmelighed, viser outputtet en redigeret pladsholder i stedet for den faktiske værdi.

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.
  • Log ikke hemmelige værdier. Stol på den automatiske hemmelige redigering i notesbogens output. Undgå at skrive hemmeligheder til filer eller sende dem som notesbogsparametre.
  • 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

putSecret gemmer en hemmelighed i det specificerede Azure Key Vault. Hvis hemmeligheden allerede eksisterer, opdateres værdien.

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

Du skal have passende tilladelser (Set tilladelse) på Azure Key Vault for at skrive hemmeligheder.

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

  • Last updated on