Nástroje na prihlasovacie údaje NotebookUtils pre Fabric

Nástroje na prihlasovacie údaje môžete použiť na získavanie prístupových tokenov a správu tajomstiev v Azure Key Vault. Modul notebookutils.credentials sa integruje s Microsoft Entra ID na získavanie tokenov a Azure Key Vault na správu tajomstiev, takže sa môžete bezpečne pripojiť k Azure zdrojom bez toho, aby ste museli vystavovať prihlasovacie údaje v kóde.

Nástroje na prihlasovacie údaje môžete použiť v Python notebookoch a Fabric Spark notebookoch. V Fabric Spark notebookoch môžete používať PySpark, Scala alebo R. Dostupnosť metódy sa líši podľa času behu notebooku a API. Napríklad funguje putSecret iba v Python zápisníkoch, ktoré používajú Python runtime. Spark notebooky to nepodporujú, ani keď bežia na Python kóde s PySparkom. Spark notebooky, ktoré používajú Scala alebo R, ho tiež nepodporujú.

Nasledujúce príklady používajú Python ako primárny jazyk. Ekvivalenty Scala a R sa objavujú tam, kde runtime notebooku a verejné API podporujú túto metódu.

Dôležité

Nikdy nekódujte tajomstvá alebo prihlasovacie údaje priamo do kódu zápisníka. Vždy používajte Azure Key Vault na ukladanie citlivých hodnôt a ich získavanie počas behu pomocou notebookutils.credentials.getSecret.

Obmedzenia a bezpečnosť

Predtým, než použijete nástroje na prihlasovacie údaje, majte na pamäti tieto obmedzenia:

  • Expirácia tokenu – Tokeny vypršia po určitom období. Pri dlhodobých operáciách implementujte obnovovaciu logiku na požiadanie o nový token pred expiráciou.
  • Obmedzenia rozsahu hlavného rozsahu služby – Pri prevádzke pod princípom služby majú tokeny pre pbi publikum obmedzený rozsah v porovnaní s identitou používateľa.
  • MSAL pre plný rozsah – Ak potrebujete celý rozsah služieb Fabric pod princípom služby, použite MSAL autentifikáciu namiesto getToken.
  • Tajná redakcia – Výstup zápisníka sa snaží začierniť pôvodnú hodnotu tajomstva, keď ju kód priamo vytlačí alebo zobrazí. Táto ochrana s najlepším úsilím znižuje náhodné odhalenie, vrátane zdieľania obrazovky. Nie je to bezpečnostná hranica. Po získaní autorizovaný kód zápisníka prijíma čistý text a môže spracovať, transformovať alebo zverejniť tajný alebo tajný obsah odvodený od tajného.
  • Oprávnenia Key Vault – Na prístup alebo ukladanie tajomstiev musíte mať príslušné oprávnenia (Get for reading, Set for writing) v Azure Key Vault.
  • Zmeny publika – Rozsah tokenového publika sa môže časom vyvíjať. Overte aktuálne rozsahy v dokumentácii.

Spustením nasledujúceho príkazu získate prehľad dostupných metód:

notebookutils.credentials.help()

Nasledujúca tabuľka uvádza dostupné metódy prihlasovacích údajov:

Method Podpis Description
getToken getToken(audience: String): String Vráti token Microsoft Entra pre zadané publikum.
getSecret getSecret(akvName: String, secret: String): String Vráti hodnotu tajomstva zo špecifikovaného Azure Key Vault.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Ukladá tajomstvo do špecifikovaného Azure Key Vault. Táto metóda funguje iba v zápisníkoch, ktoré používajú Python runtime. Spark notebooky to nepodporujú, ani keď bežia na Python kóde s PySparkom. Notebooky Spark používajúce Scala alebo R to tiež nepodporujú.
isValidToken isValidToken(token: String): Boolean Kontroluje, či je daný token platný a nie je expirovaný. Táto metóda nie je dostupná vo verejnom Scala API.

Získať token

getToken vráti token Microsoft Entra pre dané publikum. Nasledujúca tabuľka zobrazuje aktuálne dostupné kľúče pre publikum:

Kľúč k publiku Resource Prípad použitia
storage Ukladací priestor Azure Prístup k ADLS Gen2 a Blob Storage
pbi Power BI Volajte Power BI a Fabric REST API
keyvault Azure Key Vault Získanie tajomstiev Key Vaultu
kusto Synapse RTA KQL DB Connect to Azure Data Explorer

Spustite nasledujúci príkaz, aby ste získali token:

notebookutils.credentials.getToken('audience Key')

Príklady použitia tokenov

Vrátený token môžete použiť na autentifikáciu voči rôznym Azure službám.

Ukladací priestor Azure

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

Power BI a Fabric REST API

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

Použite tokeny s Azure SDK

Textilné zošity to priamo nepodporujú DefaultAzureCredential . Môžete použiť vlastnú triedu prihlasovacích údajov ako obchádzku na odovzdanie NotebookUtils tokenov klientom 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}")

Prepitné

Tokeny vypršia po určitom čase. Ak váš notebook vykonáva dlhé operácie, implementujte obnovovaciu logiku na požiadanie o nový token pred vypršaním aktuálneho.

Zváženia

  • Tokenové rozsahy s pbi publikom sa môžu časom meniť.

  • Keď voláte notebookutils.credentials.getToken("pbi"), vrátený token má obmedzený rozsah, ak notebook beží pod servisným princípom. Token nemá celý rozsah služby Fabric. Ak notebook beží pod používateľskou identitou, token má stále plný rozsah služby Fabric, ale to sa môže zmeniť s bezpečnostnými vylepšeniami. Aby ste zabezpečili, že token má plný rozsah služby Fabric, použite MSAL autentifikáciu namiesto notebookutils.credentials.getToken API. Ďalšie informácie nájdete v téme Overenie pomocou Microsoft Entra ID.

  • Nasledujúce rozsahy sú dostupné, keď voláte notebookutils.credentials.getToken s kľúčom pbi publika pod identitou hlavného operátora:

    • Lakehouse.ReadWrite.All – Prístup k čítaniu a zápisu k položkám pri jazerných domoch
    • MLExperiment.ReadWrite.All – Prístup k experimentálnym položkám na čítanie a zápis
    • MLModel.ReadWrite.All – Prístup na čítanie a zápis k položkám modelov strojového učenia
    • Notebook.ReadWrite.All – Prístup k zápisníku na čítanie a zápis
    • SparkJobDefinition.ReadWrite.All – Prístup na čítanie a zápis k položkám definície pracovných pozícií v Sparku
    • Workspace.ReadWrite.All – Prístup na čítanie a zápis do pracovných priestorov
    • Dataset.ReadWrite.All – Prístup na čítanie a zápis k sémantickým modelovým položkám

Prepitné

Ak potrebujete prístup k ďalším Fabric službám alebo širším oprávneniam v rámci servisného princípu, použite MSAL for Python na autentifikáciu priamo s plným rozsahom Fabric služby namiesto spoliehania sa na getToken("pbi").

Získanie tajnosti

getSecret vráti Azure Key Vault secret pre daný Azure Key Vault endpoint a secret name. Hovor používa vaše aktuálne používateľské údaje na autentifikáciu voči Key Vault.

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

Môžete získať viacero tajomstiev na vytvorenie spojovacích reťazcov alebo konfiguráciu služieb:

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

Dôležité

Po úspešnom získaní dostane autorizovaný kód zápisníka tajnú hodnotu ako otvorený text. Výstup zápisníka sa snaží začierniť pôvodnú hodnotu tajomstva, keď ju kód priamo vytlačí alebo zobrazí.

Táto ochrana najlepšieho úsilia znižuje náhodné odhalenie výstupu z notebooku, vrátane zdieľania obrazovky. Nie je to bezpečnostná hranica a nebráni spracovaniu, transformácii alebo zverejneniu obsahu odvodeného od tajomstiev.

Použite plne kvalifikovanú URL Key Vault vo formáte https://<vault-name>.vault.azure.net/. Musíte mať príslušné oprávnenia na prístup k Key Vaultu a jednotlivým tajomstvám.

Najlepšie bezpečnostné postupy

Riaďte sa týmito odporúčaniami, keď pracujete s kvalifikáciou v Fabric notebookoch:

  • Ukladajte všetky citlivé hodnoty do Azure Key Vault. Nikdy nevkladajte prihlasovacie údaje, spojovacie reťazce alebo API kľúče priamo do kódu notebooku.
  • Neprezrádzajte tajné hodnoty. Netlačte ani nelogujte tajomstvá, nezapisujte ich do súborov ani ich neposielajte ako parametre zápisníka. Redakcia výstupu sa snaží chrániť pôvodnú hodnotu v priamom výstupe z notebooku. Nebráni to zverejneniu tajného obsahu.
  • Použite správny kľúč pre publikum. Spojte kľúč publika s cieľovým Azure zdrojom, aby mal token len potrebné povolenia.
  • Pochopte kontext identity. Zistite, či váš notebook beží pod používateľskou identitou alebo pod princípom služby, pretože dostupné rozsahy tokenov sa môžu líšiť. Testujte autentifikáciu v interaktívnych aj pipeline kontextoch.
  • Riešiť expiráciu tokenu. Žetóny expirujú. Pri dlhodobých operáciách implementujte obnovovaciu logiku na požiadanie o nový token pred vypršaním aktuálneho.
  • Obmedzte prístup k Key Vault. Udeľte len minimálne požadované oprávnenia k vášmu Key Vaultu. Auditujte tajný prístup cez diagnostické logy Azure Key Vault.
  • Používajte spravované identity, keď je to možné. Spravované identity znižujú potrebu manuálnej správy prihlasovacích údajov a poskytujú bezpečnejší autentifikačný proces.

Daj tajomstvo

putSecretukladá alebo aktualizuje tajomstvo v špecifikovanom Azure Key Vault. Funguje len v notebookoch, ktoré používajú Python runtime.

Dôležité

Spark notebooky to nepodporujúputSecret, ani keď bežia Python kód s PySparkom. Notebooky Spark používajúce Scala alebo R to tiež nepodporujú. Použi Python notebook, ktorý využíva Python runtime.

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

Na písanie tajomstiev potrebujete príslušné oprávnenia (Set permission) na Azure Key Vault. Nasledujúci príklad spustite iba v notebooku, ktorý používa runtime v Python. Nespúšťaj to v zápisníku 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")

Validate token

Použite ho isValidToken na overenie, či je token platný a nie je expirovaný, predtým než zavoláte API s ním.

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

Súvisiaci obsah

  • Last updated on