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 sú dostupné v notebookoch Python, PySpark, Scala a R. Príklady na tejto stránke používajú Python ako primárny jazyk, pričom ekvivalenty Scala a R sú zobrazené tam, kde ich podporuje verejné API.

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 – Zápisník automaticky rediguje tajné hodnoty, aby zabránil náhodnému odhaleniu.
• 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:

jazyka Python

notebookutils.credentials.help()

Scala

notebookutils.credentials.help()

R

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 nie je dostupná vo verejnom Scala API.
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:

jazyka Python

notebookutils.credentials.getToken('audience Key')

Scala

notebookutils.credentials.getToken("audience Key")

R

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.

jazyka Python

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

Scala

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

R

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

Poznámka

Zápisník automaticky rediguje tajné hodnoty kvôli bezpečnosti. Ak vytlačíte alebo zobrazíte získané tajomstvo, výstup zobrazí redigovaný zástupný symbol namiesto skutočnej hodnoty.

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.
• Nezaznamenávajte tajné hodnoty. Spoľahnite sa na automatickú tajnú cenzuru výstupov z notebooku. Vyhnite sa zapisovaniu tajomstiev do súborov alebo ich posielaniu ako parametrov zápisníka.
• 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

putSecret ukladá tajomstvo do špecifikovaného Azure Key Vault. Ak tajomstvo už existuje, jeho hodnota sa aktualizuje.

jazyka Python

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

Scala

Poznámka

putSecret nie je dostupný v verejnom Scala API. Používajte Python, PySpark alebo R notebooky, keď potrebujete napísať tajomstvo do Azure Key Vault z NotebookUtils.

R

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

Na zapisovanie tajomstiev musíte mať na Azure Key Vault príslušné oprávnenia (Set permission).

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.

jazyka Python

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

Scala

Poznámka

isValidToken nie je dostupný v verejnom Scala API. V zápisníkoch Scala požiadajte o nový token, keď je to potrebné, namiesto toho, aby ste volali tohto pomocníka.

R

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

Súvisiaci obsah

• NotebookUtils (bývalý MSSparkUtils) pre Fabric