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.

Die Anmeldeinformationen-Dienstprogramme sind in Python, PySpark, Scala und R Notizbüchern verfügbar. Die Beispiele auf dieser Seite verwenden Python als primäre Sprache, wobei Skala und R-Entsprechungen gezeigt werden, wo die öffentliche API sie unterstützt.

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.
• Geheime Redaktion – Das Notizbuch redigiert automatisch geheime Werte, um versehentliche Offenlegung zu verhindern.
• 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()

notebookutils.credentials.help()

notebookutils.credentials.help()

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

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:

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

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

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

Ü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-Elemente
  • MLExperiment.ReadWrite.All – Lese- und Schreibzugriff auf Machine Learning Experiment-Elemente
  • MLModel.ReadWrite.All – Lese- und Schreibzugriff auf Machine Learning-Modellelemente
  • Notebook.ReadWrite.All – Lese- und Schreibzugriff auf Notizbuchelemente
  • SparkJobDefinition.ReadWrite.All – Lese- und Schreibzugriff auf Spark Job Definition-Elemente
  • Workspace.ReadWrite.All – Lese- und Schreibzugriff auf Arbeitsbereichselemente
  • Dataset.ReadWrite.All – Lese- und Schreibzugriff auf Datasetelemente

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

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

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

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.
• Protokollieren Sie keine geheimen Werte. Verlassen Sie sich auf die automatische geheime Redaction in den Notizbuchausgaben. Vermeiden Sie das Schreiben von Geheimnissen in Dateien oder die Übergabe als Notebook-Parameter.
• 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 einen geheimen Schlüssel im angegebenen Azure Key Vault. Wenn der geheime Schlüssel bereits vorhanden ist, wird der Wert aktualisiert.

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

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

Sie müssen über entsprechende Berechtigungen (Berechtigung festlegen) im Azure Key Vault verfügen, um geheime Schlüssel zu schreiben.

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

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

Verwandte Inhalte

• NotebookUtils (ehemalige MSSparkUtils) für Fabric