Dienstprogramme für Anmeldeinformationen von NotebookUtils für Fabric

Sie können die Anmeldeinformationen-Tools verwenden, um Zugriffstoken abzurufen und Secrets in Azure Key Vault zu verwalten. Das notebookutils.credentials Modul ist in die Microsoft Entra-ID für die Token-Erfassung und Azure Key Vault für das Geheimnismanagement integriert, sodass Sie sicher eine Verbindung mit Azure-Ressourcen herstellen können, ohne dass Anmeldeinformationen im Code offengelegt werden.

Du kannst die Zugangsdienstprogramme in Python-Notebooks und Fabric Spark-Notebooks verwenden. In Fabric Spark-Notebooks können Sie PySpark, Scala oder R verwenden. Die Verfügbarkeit der Methoden variiert je nach Notebook-Laufzeit und API. Zum Beispiel putSecret funktioniert es nur in Python-Notebooks, die die Python-Laufzeit verwenden. Spark-Notebooks unterstützen das nicht, selbst wenn sie Python-Code mit PySpark ausführen. Spark-Notizbücher, die Scala oder R verwenden, unterstützen das ebenfalls nicht.

Die folgenden Beispiele verwenden Python als Hauptsprache. Scala- und R-Äquivalente erscheinen dort, wo die Notebook-Laufzeit und die öffentliche API die Methode unterstützen.

Von Bedeutung

Niemals geheime Schlüssel oder Anmeldeinformationen direkt im Notizbuchcode codieren. Verwenden Sie immer Azure Key Vault, um vertrauliche Werte zu speichern und während der Laufzeit mit notebookutils.credentials.getSecret abzurufen.

Einschränkungen und Sicherheit

Bevor Sie Tools für Anmeldeinformationen verwenden, beachten Sie diese Einschränkungen:

  • Tokenablauf – Token laufen nach einem Zeitraum ab. Implementieren Sie bei langandauernden Vorgängen einen Aktualisierungsmechanismus, um ein neues Token vor dem Ablauf anzufordern.
  • Einschränkungen des Dienstprinzipalbereichs – Bei der Ausführung unter einem Dienstprinzipal weisen Token für die pbi Zielgruppe im Vergleich zur Benutzeridentität eingeschränkte Bereiche auf.
  • MSAL für den vollständigen Bereich – Wenn Sie den vollständigen Fabric-Dienstbereich unter einem Dienstprinzipal benötigen, verwenden Sie die MSAL-Authentifizierung anstelle von getToken.
  • Schwärzung von Geheimnissen – Die Notebook-Ausgabe versucht, den ursprünglichen Geheimniswert zu schwärzen, wenn der Code ihn direkt ausgibt oder anzeigt. Diese Best-Effort-Schutzmaßnahme reduziert die versehentliche Offenlegung von Informationen, auch bei der Bildschirmfreigabe. Es ist keine Sicherheitsgrenze. Nach dem Abruf erhält der autorisierte Notizbuchcode den Klartext und kann den geheimen oder geheimnisabgeleiteten Inhalt verarbeiten, transformieren oder offenlegen.
  • Schlüsseltresorberechtigungen – Sie müssen über entsprechende Berechtigungen verfügen (Zum Lesen abrufen, zum Schreiben festlegen) im Azure Key Vault, um auf geheime Schlüssel zuzugreifen oder zu speichern.
  • Benutzergruppenänderungen – Token-Zielgruppenbereiche können sich im Laufe der Zeit weiterentwickeln. Überprüfen Sie die aktuellen Geltungsbereiche in der Dokumentation.

Führen Sie den folgenden Befehl aus, um eine Übersicht über die verfügbaren Methoden zu erhalten:

notebookutils.credentials.help()

In der folgenden Tabelle sind die verfügbaren Anmeldemethoden aufgeführt:

Methode Signature Beschreibung
getToken getToken(audience: String): String Gibt ein Microsoft Entra-Token für die angegebene Zielgruppe zurück.
getSecret getSecret(akvName: String, secret: String): String Gibt den Wert eines geheimen Schlüssels aus dem angegebenen Azure Key Vault zurück.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Speichert einen geheimen Schlüssel im angegebenen Azure Key Vault. Diese Methode funktioniert nur in Notebooks, die die Python-Laufzeit verwenden. Spark-Notebooks unterstützen das nicht, selbst wenn sie Python-Code mit PySpark ausführen. Spark-Notizbücher, die Scala oder R verwenden, unterstützen das ebenfalls nicht.
isValidToken isValidToken(token: String): Boolean Überprüft, ob das angegebene Token gültig und nicht abgelaufen ist. Diese Methode ist in der öffentlichen Scala-API nicht verfügbar.

Token abrufen

getToken gibt ein Microsoft Entra-Token für eine bestimmte Zielgruppe zurück. Die folgende Tabelle zeigt die derzeit verfügbaren Benutzergruppenschlüssel:

Zielgruppenschlüssel Ressource Anwendungsfall
storage Azure Storage Zugreifen auf ADLS Gen2 und Blob Storage
pbi Power BI Aufrufen von Power BI- und Fabric-REST-APIs
keyvault Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel) Abrufen der Key Vault-Geheimnisse
kusto Synapse RTA KQL DB Herstellen einer Verbindung mit Azure Data Explorer

Führen Sie den folgenden Befehl aus, um das Token abzurufen:

notebookutils.credentials.getToken('audience Key')

Beispiele für Token-Nutzung

Sie können das zurückgegebene Token verwenden, um sich bei verschiedenen Azure-Diensten zu authentifizieren.

Azure Storage

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

Power BI- und Fabric-REST-APIs

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 (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel)

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

Verwenden von Token mit dem Azure SDK

Fabric-Notizbücher unterstützen DefaultAzureCredential nicht direkt. Sie können eine benutzerdefinierte Anmeldeinformationsklasse als Problemumgehung verwenden, um NotebookUtils-Token an Azure SDK-Clients zu übergeben.

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

Tipp

Token laufen nach einem bestimmten Zeitraum ab. Wenn Ihr Notizbuch lange Vorgänge ausführt, implementieren Sie die Aktualisierungslogik, um ein neues Token anzufordern, bevor das aktuelle abläuft.

Überlegungen

  • Token-Bereiche mit pbi als Zuhörer können sich im Laufe der Zeit ändern.

  • Wenn Sie notebookutils.credentials.getToken("pbi") aufrufen, hat das zurückgegebene Token einen eingeschränkten Gültigkeitsbereich, wenn das Notizbuch unter einem Dienstprinzipal ausgeführt wird. Das Token verfügt nicht über den vollständigen Fabric-Dienstbereich. Wenn das Notizbuch unter der Benutzeridentität ausgeführt wird, weist das Token weiterhin den vollständigen Fabric-Dienstbereich auf, dies kann sich jedoch mit Sicherheitsverbesserungen ändern. Um sicherzustellen, dass das Token über den vollständigen Fabric-Dienstbereich verfügt, verwenden Sie die MSAL-Authentifizierung anstelle der notebookutils.credentials.getToken API. Weitere Informationen finden Sie unter "Authentifizieren mit Microsoft Entra ID".

  • Die folgenden Bereiche sind verfügbar, wenn Sie mit dem Benutzergruppenschlüssel notebookutils.credentials.getToken unter der Dienstprinzipalidentität anrufenpbi:

    • Lakehouse.ReadWrite.All – Lese- und Schreibzugriff auf Lakehouse-Artikel
    • MLExperiment.ReadWrite.All – Lese- und Schreibzugriff auf Experimentobjekte
    • MLModel.ReadWrite.All – Lese- und Schreibzugriff auf ML-Modellelemente
    • Notebook.ReadWrite.All – Lese- und Schreibzugriff auf Notizbucheinträge
    • SparkJobDefinition.ReadWrite.All – Lese- und Schreibzugriff auf Spark-Jobdefinitionselemente
    • Workspace.ReadWrite.All – Lese- und Schreibzugriff auf Arbeitsbereiche
    • Dataset.ReadWrite.All – Lese- und Schreibzugriff auf semantische Modellelemente

Tipp

Wenn Sie Zugriff auf zusätzliche Fabric-Dienste oder umfassendere Berechtigungen unter einem Dienstprinzipal benötigen, verwenden Sie MSAL für Python , um sich direkt mit dem vollständigen Fabric-Dienstbereich zu authentifizieren, anstatt sich auf getToken("pbi")zu verlassen.

Geheimen Schlüssel abrufen

getSecret gibt einen geheimen Azure Key Vault-Schlüssel für einen bestimmten Azure Key Vault-Endpunkt und geheimen Namen zurück. Der Aufruf verwendet Ihre aktuellen Benutzeranmeldeinformationen, um sich bei Key Vault zu authentifizieren.

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

Sie können mehrere geheime Schlüssel abrufen, um Verbindungszeichenfolgen zu erstellen oder Dienste zu konfigurieren:

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

Von Bedeutung

Nach erfolgreichem Abruf erhält der autorisierte Notizbuchcode den geheimen Wert als Klartext. Die Notebook-Ausgabe versucht, den ursprünglichen geheimen Wert unkenntlich zu machen, wenn der Code ihn direkt ausgibt oder anzeigt.

Diese Schutzmaßnahme nach dem Best-Effort-Prinzip reduziert die versehentliche Preisgabe in der Notebook-Ausgabe, auch bei der Bildschirmfreigabe. Es ist keine Sicherheitsgrenze und verhindert nicht die Verarbeitung, Transformation oder Offenlegung von geheimnisbasierten Inhalten.

Verwenden Sie die vollqualifizierte Key Vault-URL im Format https://<vault-name>.vault.azure.net/. Sie müssen über entsprechende Berechtigungen für den Zugriff auf den Key Vault und die einzelnen geheimen Schlüssel verfügen.

Bewährte Methoden für Sicherheit

Befolgen Sie diese Empfehlungen, wenn Sie mit Anmeldeinformationen in Fabric-Notizbüchern arbeiten:

  • Speichern Sie alle vertraulichen Werte in Azure Key Vault. Betten Sie niemals Anmeldeinformationen, Verbindungszeichenfolgen oder API-Schlüssel direkt in den Notizbuchcode ein.
  • Geben Sie keine geheimen Werte preis. Geben Sie keine Geheimnisse aus, protokollieren Sie sie nicht, schreiben Sie sie nicht in Dateien, und übergeben Sie sie nicht als Notebook-Parameter. Die Ausgabeschwärzung versucht, den ursprünglichen Wert in der direkten Ausgabe im Notebook zu schützen. Es verhindert nicht die Offenlegung von geheim abgeleiteten Inhalten.
  • Verwenden Sie den richtigen Zielgruppenschlüssel. Stimmen Sie den Zielgruppenschlüssel mit der Azure-Zielressource überein, sodass das Token nur über die erforderlichen Berechtigungen verfügt.
  • Verstehen des Identitätskontexts. Wissen Sie, ob Ihr Notizbuch unter Benutzeridentität oder einem Dienstprinzipal ausgeführt wird, da sich die verfügbaren Tokenbereiche unterscheiden können. Testen Sie die Authentifizierung sowohl in interaktiven als auch in Pipelinekontexten.
  • Umgang mit dem Ablaufen von Tokens. Token laufen ab. Implementieren Sie für lange ausgeführte Vorgänge Aktualisierungslogik, um ein neues Token anzufordern, bevor das aktuelle abläuft.
  • Beschränken Sie den Schlüsseltresorzugriff. Erteilen Sie nur die minimal erforderlichen Berechtigungen für Ihren Key Vault. Überwachen des geheimen Zugriffs über Azure Key Vault-Diagnoseprotokolle.
  • Verwenden Sie verwaltete Identitäten, wenn möglich. Verwaltete Identitäten reduzieren die Notwendigkeit, Anmeldeinformationen manuell zu verwalten und einen sichereren Authentifizierungsfluss bereitzustellen.

Geheimen Schlüssel setzen

putSecret speichert oder aktualisiert ein Geheimnis im angegebenen Azure Key Vault. Es funktioniert nur in Notebooks, die die Python-Laufzeit verwenden.

Von Bedeutung

Spark-Notebooks unterstützen putSecret nicht, selbst wenn darin Python-Code mit PySpark ausgeführt wird. Spark-Notizbücher, die Scala oder R verwenden, unterstützen das ebenfalls nicht. Verwende ein Python-Notebook, das die Python-Laufzeit nutzt.

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

Um Geheimnisse zu schreiben, benötigen Sie entsprechende Berechtigungen (Set Permission) im Azure Key Vault. Führe das folgende Beispiel nur in einem Notebook aus, das die Python-Laufzeit verwendet. Führe es nicht in einem Fabric Spark-Notizbuch ein.

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

Token überprüfen

Verwenden Sie diese Option isValidToken , um zu überprüfen, ob ein Token gültig ist und nicht abgelaufen ist, bevor Sie eine API aufrufen.

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

Verwandte Inhalte

  • Last updated on