NotebookUtils le utilità delle credenziali per Fabric

È possibile usare le utilità delle credenziali per ottenere i token di accesso e gestire i segreti in Azure Key Vault. Il notebookutils.credentials modulo si integra con Microsoft Entra ID per l'acquisizione di token e Azure Key Vault per la gestione dei segreti, in modo da potersi connettere in modo sicuro alle risorse di Azure senza esporre le credenziali nel codice.

Puoi usare le utility di credenziali nei quaderni Python e Fabric Spark. Nei notebook Fabric Spark, puoi usare PySpark, Scala o R. La disponibilità dei metodi varia a seconda dell'runtime del notebook e dell'API. Ad esempio, putSecret funziona solo nei quaderni Python, che utilizzano il runtime Python. I notebook Spark non lo supportano, nemmeno quando eseguono codice Python con PySpark. Anche i notebook Spark che usano Scala o R non lo supportano.

I seguenti esempi utilizzano Python come linguaggio principale. Gli equivalenti scala e R appaiono dove il runtime del notebook e l'API pubblica supportano il metodo.

Importante

Non inserire mai segreti o credenziali codificati staticamente direttamente nel codice del notebook. Usare sempre Azure Key Vault per archiviare i valori sensibili e recuperarli in fase di esecuzione con notebookutils.credentials.getSecret.

Vincoli e sicurezza

Prima di usare le utilità delle credenziali, tenere presente questi vincoli:

  • Scadenza del token : i token scadono dopo un periodo. Per le operazioni a esecuzione prolungata, implementare la logica di aggiornamento per richiedere un nuovo token prima della scadenza.
  • Limitazioni dell'ambito dell'entità servizio : quando sono in esecuzione in un'entità servizio, i token per il pbi gruppo di destinatari hanno ambiti limitati rispetto all'identità utente.
  • MSAL per l'ambito completo : se è necessario l'ambito completo del servizio Fabric in un'entità servizio, usare l'autenticazione MSAL anziché getToken.
  • Redattura segreta – L'output del notebook tenta di oscurare il valore segreto originale quando il codice lo stampa o lo visualizza direttamente. Questa salvaguardia del miglior sforzo riduce la divulgazione accidentale, anche durante la condivisione dello schermo. Non è un confine di sicurezza. Dopo il recupero, il codice autorizzato del notebook riceve testo in chiaro e può elaborare, trasformare o divulgare il contenuto segreto o derivato dal segreto.
  • Autorizzazioni del Key Vault – È necessario disporre delle autorizzazioni appropriate (ottenere per la lettura, impostare per la scrittura) sul Key Vault di Azure per accedere o archiviare i segreti.
  • Modifiche del gruppo di destinatari : gli ambiti del gruppo di destinatari dei token possono evolversi nel tempo. Verificare gli ambiti correnti nella documentazione.

Usare il comando seguente per ottenere una panoramica dei metodi disponibili:

notebookutils.credentials.help()

Nella tabella seguente sono elencati i metodi di credenziali disponibili:

metodo Firma Descrizione
getToken getToken(audience: String): String Restituisce un token Microsoft Entra per il gruppo di destinatari specificato.
getSecret getSecret(akvName: String, secret: String): String Restituisce il valore di un segreto dal Key Vault di Azure specificato.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Archivia un segreto nello specifico Azure Key Vault. Questo metodo funziona solo nei notebook che utilizzano il runtime Python. I notebook Spark non lo supportano, nemmeno quando eseguono codice Python con PySpark. Anche i notebook Spark che usano Scala o R non lo supportano.
isValidToken isValidToken(token: String): Boolean Controlla se il token specificato è valido e non è scaduto. Questo metodo non è disponibile nell'API Scala pubblica.

Ottenere un token

getToken restituisce un token Microsoft Entra per un determinato gruppo di destinatari. La tabella seguente illustra le chiavi di gruppo di destinatari attualmente disponibili:

Chiave destinatari risorsa caso d'uso
storage Archiviazione di Azure Accedere ad ADLS Gen2 e all'archiviazione BLOB
pbi Power BI Chiamare le API REST di Power BI e Fabric
keyvault Azure Key Vault (Archivio chiavi di Azure) Recuperare i segreti di Key Vault
kusto Synapse RTA KQL DB Connettersi a Esplora dati di Azure

Usare il comando seguente per ottenere il token:

notebookutils.credentials.getToken('audience Key')

Esempi di utilizzo dei token

È possibile usare il token restituito per eseguire l'autenticazione in diversi servizi di Azure.

Archiviazione di Azure

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

API REST di Power BI e Fabric

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

Esplora dati di Azure (Kusto)

kusto_token = notebookutils.credentials.getToken('kusto')

Azure Key Vault (Archivio chiavi di Azure)

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

Usare i token con il Azure SDK

I notebook Fabric non supportano direttamente DefaultAzureCredential. È possibile usare una classe di credenziali personalizzata come soluzione alternativa per passare i token NotebookUtils ai client Azure SDK.

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

Suggerimento

I token scadono dopo un periodo di tempo. Se il notebook esegue operazioni lunghe, implementare la logica di aggiornamento per richiedere un nuovo token prima che scada quello corrente.

Considerazioni

  • Gli ambiti del token con pbi come pubblico possono cambiare nel tempo.

  • Quando si chiama notebookutils.credentials.getToken("pbi"), il token restituito ha un ambito limitato se il notebook viene eseguito con un principal di servizio. Il token non ha l'ambito completo del servizio Fabric. Se il notebook viene eseguito con l'identità utente, il token conserva l'intero ambito del servizio Fabric, ma questo potrebbe cambiare con i miglioramenti della sicurezza. Per assicurarsi che il token abbia l'ambito completo del servizio Fabric, usare l'autenticazione MSAL anziché l'API notebookutils.credentials.getToken . Per altre informazioni, vedere Eseguire l'autenticazione con Microsoft Entra ID.

  • Quando si chiama notebookutils.credentials.getToken con la chiave pbi del gruppo di destinatari nell'identità dell'entità servizio, sono disponibili gli ambiti seguenti:

    • Lakehouse.ReadWrite.All – Accesso in lettura e scrittura agli elementi del lakehouse
    • MLExperiment.ReadWrite.All – Accesso per leggere e scrivere agli elementi sperimentali
    • MLModel.ReadWrite.All – Accesso per lettura e scrittura agli elementi del modello ML
    • Notebook.ReadWrite.All – Accesso per leggere e scrivere agli elementi del quaderno
    • SparkJobDefinition.ReadWrite.All – Accesso per leggere e scrivere agli elementi di definizione del lavoro Spark
    • Workspace.ReadWrite.All – Accesso per lettura e scrittura agli spazi di lavoro
    • Dataset.ReadWrite.All – Accesso per leggere e scrivere agli elementi del modello semantico

Suggerimento

Se hai bisogno di accedere a ulteriori servizi Fabric o a autorizzazioni più ampie come proprietario del servizio, usa MSAL per Python per autenticarti direttamente con l'ambito completo del servizio Fabric anziché basarti su getToken("pbi").

Ottenere il segreto

getSecret restituisce un segreto di Azure Key Vault per un determinato endpoint di Azure Key Vault e un nome segreto. La chiamata usa le credenziali utente correnti per l'autenticazione in Key Vault.

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

È possibile recuperare più segreti per compilare stringhe di connessione o configurare i servizi:

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

Importante

Dopo il recupero riuscito, il codice del notebook autorizzato riceve il valore segreto come testo in chiaro. L'output del notebook tenta di oscurare il valore segreto originale quando il codice lo stampa o lo visualizza direttamente.

Questa misura di protezione basata sul principio del massimo sforzo riduce il rischio di divulgazione accidentale nell'output del notebook, anche durante la condivisione dello schermo. Non è un confine di sicurezza e non impedisce l'elaborazione, la trasformazione o la divulgazione di contenuti derivati da segreti.

Usare l'URL completamente qualificato di Key Vault nel formato https://<vault-name>.vault.azure.net/. È necessario disporre delle autorizzazioni appropriate per accedere al Key Vault e ai singoli segreti.

Procedure consigliate per la sicurezza

Seguire questi consigli quando si lavora con le credenziali nei notebook di Fabric:

  • Archiviare tutti i valori sensibili in Azure Key Vault. Non incorporare mai credenziali, stringhe di connessione o chiavi API direttamente nel codice del notebook.
  • Non rivelare valori segreti. Non stampare o registrare segreti, scrivili nei file e non passarli come parametri di notebook. L'oscuramento dell'output ha lo scopo di proteggere il valore originale nell'output diretto nel notebook. Non impedisce la divulgazione di contenuti derivati da segreti.
  • Usare la chiave di pubblico corretta. Associare la chiave di gruppo di destinatari alla risorsa di Azure di destinazione in modo che il token disponga solo delle autorizzazioni necessarie.
  • Comprendere il contesto di identità. Sapere se il notebook viene eseguito con un'identità utente o un principal del servizio, poiché gli ambiti del token disponibili possono variare. Testare l'autenticazione in contesti interattivi e pipeline.
  • Gestire la scadenza del token. I token scadranno. Per le operazioni a esecuzione prolungata, implementare la logica di aggiornamento per richiedere un nuovo token prima della scadenza di quella corrente.
  • Limitare l'accesso a Key Vault. Concedere solo le autorizzazioni minime necessarie al Key Vault. Controllare l'accesso segreto tramite i log di diagnostica di Azure Key Vault.
  • Usare le identità gestite quando possibile. Le identità gestite riducono la necessità di gestire manualmente le credenziali e fornire un flusso di autenticazione più sicuro.

Inserisci segreto

putSecretmemorizza o aggiorna un segreto nell'Azure Key Vault specificato. Funziona solo nei notebook che utilizzano il runtime Python.

Importante

I quaderni Spark non supportanoputSecret, nemmeno quando eseguono codice Python con PySpark. Anche i notebook Spark che usano Scala o R non lo supportano. Usa un notebook Python, che utilizza il runtime Python.

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

Per scrivere segreti, servono i permessi appropriati (imposta permesso) sull'Azure Key Vault. Esegui il seguente esempio solo in un notebook che utilizza il runtime Python. Non eseguirlo in un notebook Fabric Spark.

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

Convalidare il token

Usare isValidToken per verificare se un token è valido e non scaduto prima di chiamare un'API con esso.

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

Contenuti correlati

  • Last updated on