Condividi tramite

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.

Le utilità delle credenziali sono disponibili nei notebook Python, PySpark, Scala e R. Gli esempi in questa pagina usano Python come linguaggio primario, con gli equivalenti Scala e R indicati in cui l'API pubblica li supporta.

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.
  • Redazione segreta – gli output dei notebook oscurano automaticamente le informazioni sensibili per evitare l'esposizione accidentale.
  • 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 non è disponibile nell'API Scala pubblica.
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 Azure Storage 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.

Azure Storage

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 Lakehouse
    • MLExperiment.ReadWrite.All – Accesso in lettura e scrittura agli elementi dell'esperimento di Machine Learning
    • MLModel.ReadWrite.All – Accesso in lettura e scrittura agli elementi del modello di Machine Learning
    • Notebook.ReadWrite.All – Accesso in lettura e scrittura agli elementi del notebook
    • SparkJobDefinition.ReadWrite.All – Accesso in lettura e scrittura agli elementi di definizione del job Spark
    • Workspace.ReadWrite.All – Accesso in lettura e scrittura agli elementi dell'area di lavoro
    • Dataset.ReadWrite.All – Accesso in lettura e scrittura agli elementi del set di dati

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

Annotazioni

Gli output dei notebook redigono automaticamente i valori riservati a fini di sicurezza. Se si stampa o si visualizza un segreto recuperato, l'output mostra un segnaposto redatto anziché il valore effettivo.

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 registrare i valori segreti. Fare affidamento sulla redazione automatica delle informazioni riservate negli output dei notebook. Evitare di scrivere segreti nei file o di passarli come parametri del notebook.
  • 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

putSecret archivia un segreto nel Vault delle chiavi di Azure specificato. Se il segreto esiste già, il valore viene aggiornato.

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

Per scrivere segreti, è necessario disporre delle autorizzazioni appropriate (configurare le autorizzazioni) su Azure Key Vault.

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