Nástroje pro práci s přihlašovacími údaji ve Frameworku NotebookUtils pro Fabric

Pomocí nástrojů pro přihlašovací údaje můžete získat přístupové tokeny a spravovat tajné kódy ve službě Azure Key Vault. Modul notebookutils.credentials se integruje s Microsoft Entra ID pro získání tokenů a Azure Key Vault pro správu tajných kódů, abyste se mohli bezpečně připojit k prostředkům Azure bez vystavení přihlašovacích údajů v kódu.

Nástroje pro přihlašovací údaje můžete použít v Python notebookech a Fabric Spark notebookech. V zápisnících Fabric Spark můžete používat PySpark, Scala nebo R. Dostupnost metody se liší podle běhu notebooku a API. Například funguje putSecret pouze v Python zápisnících, které používají Python runtime. Notebooky Spark to nepodporují, ani když běží Python kód s PySparkem. Notebooky Spark, které používají Scalu nebo R, to také nepodporují.

Následující příklady používají Python jako hlavní jazyk. Ekvivalenty Scala a R se objevují tam, kde tuto metodu podporují runtime notebooku a veřejné API.

Důležité

Nikdy pevně nezakódujte tajné kódy ani přihlašovací údaje přímo v kódu poznámkového bloku. Vždy používejte Azure Key Vault k ukládání citlivých hodnot a jejich načítání za běhu pomocí notebookutils.credentials.getSecret.

Omezení a bezpečnost

Než použijete nástroje pro přihlašovací údaje, mějte na paměti tato omezení:

  • Vypršení platnosti tokenu – Platnost tokenů vyprší po určité době. U dlouhotrvajících operací implementujte logiku aktualizace pro vyžádání nového tokenu před vypršením platnosti.
  • Omezení oboru instančního objektu – Při spuštění v rámci instančního objektu mají tokeny pro pbi cílovou skupinu omezené obory v porovnání s identitou uživatele.
  • MSAL pro úplný rozsah – Pokud potřebujete úplný obor služby Fabric v rámci služebního principála, použijte ověřování MSAL místo toho getToken.
  • Redigování tajných údajů – Výstup notebooku se pokusí skrýt původní hodnotu tajného údaje, pokud ji kód přímo vytiskne nebo zobrazí. Toto ochranné opatření fungující podle principu best effort omezuje nechtěné zpřístupnění informací, a to i při sdílení obrazovky. Není to bezpečnostní hranice. Po načtení autorizovaný kód poznámkového bloku obdrží prostý text a může zpracovat, transformovat nebo zpřístupnit tajný údaj či obsah odvozený z tajného údaje.
  • Oprávnění služby Key Vault – Pro přístup k tajným kódům nebo jejich ukládání musíte mít příslušná oprávnění (Získat pro čtení, Nastavit pro zápis) ve službě Azure Key Vault.
  • Změny cílové skupiny – Rozsahy cílových skupin tokenů se můžou v průběhu času vyvíjet. V dokumentaci ověřte aktuální rozsahy.

Spuštěním následujícího příkazu získejte přehled dostupných metod:

notebookutils.credentials.help()

Následující tabulka uvádí dostupné metody přihlašovacích údajů:

Metoda Signature Description
getToken getToken(audience: String): String Vrátí token Microsoft Entra pro zadanou cílovou skupinu.
getSecret getSecret(akvName: String, secret: String): String Vrátí hodnotu tajemství ze zadaného Azure Key Vault.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Uloží tajný údaj do zadané služby Azure Key Vault. Tato metoda funguje pouze v notebocích, které používají Python runtime. Notebooky Spark to nepodporují, ani když běží Python kód s PySparkem. Notebooky Spark používající Scalu nebo R to také nepodporují.
isValidToken isValidToken(token: String): Boolean Zkontroluje, jestli je daný token platný a nevypršela jeho platnost. Tato metoda není dostupná ve veřejném rozhraní Scala API.

Získání tokenu

getToken vrátí token Microsoft Entra pro danou cílovou skupinu. V následující tabulce jsou uvedeny aktuálně dostupné klíče cílové skupiny:

Klíč cílové skupiny zdroj Případ použití
storage Azure Storage Přístup k ADLS Gen2 a Blob Storage
pbi Power BI Volání rozhraní REST API Power BI a Fabric
keyvault Azure Key Vault Načtení tajných kódů služby Key Vault
kusto Synapse RTA KQL DB Připojení k Průzkumníku dat Azure

Spuštěním následujícího příkazu získejte token:

notebookutils.credentials.getToken('audience Key')

Příklady použití tokenů

Vrácený token můžete použít k ověření v různých službách Azure.

Azure Storage

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

Rozhraní REST API pro Power BI a 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")

Azure Data Explorer (Kusto)

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

Azure Key Vault

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

Použití tokenů se sadou Azure SDK

Poznámkové bloky Fabric přímo nepodporují DefaultAzureCredential. Jako alternativní řešení můžete použít vlastní třídu přihlašovacích údajů k předání tokenů NotebookUtils klientům sady 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}")

Návod

Platnost tokenů vyprší po určité době. Pokud váš notebook provádí dlouhé operace, implementujte logiku obnovování, která před vypršením platnosti aktuálního tokenu vyžádá nový token.

Úvahy

  • Rozsahy tokenů s pbi cílovou skupinou se můžou v průběhu času měnit.

  • Při volání notebookutils.credentials.getToken("pbi") má vrácený token omezený rozsah, pokud se poznámkový blok spouští pod služebním principálem. Token nemá úplný obor služby Fabric. Pokud poznámkový blok běží pod identitou uživatele, token má stále plný rozsah služby Fabric, ale to se může změnit s dalšími vylepšeními zabezpečení. Pokud chcete zajistit, aby token měl úplný rozsah služeb Fabric, použijte místo rozhraní API ověřování MSAL pomocí notebookutils.credentials.getToken. Další informace naleznete v tématu Ověřování pomocí Microsoft Entra ID.

  • Při volání notebookutils.credentials.getToken s audience klíčem pbi v rámci identity hlavního objektu služby jsou k dispozici následující obory:

    • Lakehouse.ReadWrite.All – Přístup pro čtení a zápis k položkám Lakehouse
    • MLExperiment.ReadWrite.All – Přístup k experimentálním položkám pro čtení a zápis
    • MLModel.ReadWrite.All – Přístup ke čtení a zápisu k modelovým položkám ML
    • Notebook.ReadWrite.All – Přístup ke čtení a zápisu k položkám v zápisníku
    • SparkJobDefinition.ReadWrite.All – Přístup k definicím pracovních pozic ve Sparku pro čtení a zápis
    • Workspace.ReadWrite.All – Přístup ke čtení a zápisu do pracovních prostor
    • Dataset.ReadWrite.All – Přístup ke sémantickým modelům pro čtení a zápis

Návod

Pokud potřebujete přístup k dalším službám Fabric nebo širším oprávněním v rámci aplikačního objektu, použijte MSAL pro Python k přímému ověření pomocí kompletního přístupu ke službám Fabric, místo spoléhání se na getToken("pbi").

Získání tajného kódu

getSecret vrátí tajný klíč služby Azure Key Vault pro daný koncový bod služby Azure Key Vault a název tajného kódu. Volání používá vaše aktuální přihlašovací údaje uživatele k ověření ve službě Key Vault.

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

Můžete načíst více tajných kódů pro sestavení připojovacích řetězců nebo konfiguraci služeb:

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 úspěšném získání přijímá autorizovaný kód zápisníku tajnou hodnotu jako otevřený text. Výstup z notebooku se pokouší skrýt původní hodnotu tajného údaje, pokud ji kód přímo vypíše nebo zobrazí.

Toto ochranné opatření fungující na principu best-effort omezuje náhodné zpřístupnění výstupu v notebooku, a to i při sdílení obrazovky. Není to bezpečnostní hranice a nebrání zpracování, transformaci nebo zveřejnění obsahu odvozeného od tajemství.

Použijte plně kvalifikovanou adresu URL služby Key Vault ve formátu https://<vault-name>.vault.azure.net/. Pro přístup ke službě Key Vault a jednotlivým tajným klíčům musíte mít odpovídající oprávnění.

Osvědčené postupy zabezpečení

Při práci s přihlašovacími údaji v poznámkových blocích Fabric postupujte podle těchto doporučení:

  • Uložte všechny citlivé hodnoty ve službě Azure Key Vault. Nikdy nevkládejte přihlašovací údaje, připojovací řetězce ani klíče rozhraní API přímo do kódu poznámkového bloku.
  • Neprozrazujte tajné hodnoty. Netiskněte ani nelogujte tajemství, nezapisujte je do souborů ani je nepředávájte jako parametry notebooku. Redakce výstupu se snaží chránit původní hodnotu v přímém výstupu z notebooku. Nebrání zveřejnění obsahu odvozeného z tajemství.
  • Použijte správný klíč pro cílovou skupinu. Shodujte klíč cílové skupiny s cílovým prostředkem Azure, aby token měl jenom potřebná oprávnění.
  • Seznamte se s kontextem identity. Zjistěte, jestli se váš poznámkový blok spouští pod identitou uživatele nebo instančním objektem, protože dostupné obory tokenů se můžou lišit. Otestujte ověřování v interaktivním kontextu i v kontextu roury.
  • Zpracování vypršení platnosti tokenu Platnost tokenů vyprší. V případě dlouhotrvajících operací implementujte logiku aktualizace pro vyžádání nového tokenu před vypršením platnosti aktuálního tokenu.
  • Omezte přístup ke službě Key Vault. Udělte službě Key Vault jenom minimální požadovaná oprávnění. Auditovat přístup k tajným kódům prostřednictvím diagnostických protokolů služby Azure Key Vault.
  • Pokud je to možné, používejte spravované identity. Spravované identity snižují potřebu ruční správy přihlašovacích údajů a poskytují bezpečnější tok ověřování.

Zadejte tajný klíč

putSecretukládá nebo aktualizuje tajemství ve specifikovaném Azure Key Vault. Funguje to pouze v noteboích používajících Python runtime.

Důležité

Spark notebooky to nepodporujíputSecret, ani když běží Python kód s PySparkem. Notebooky Spark používající Scalu nebo R to také nepodporují. Použijte Python notebook, který využívá Python runtime.

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

Pro zápis tajemství potřebujete příslušná oprávnění (Set permission) na Azure Key Vault. Následující příklad spusťte pouze v notebooku, který používá runtime Python. Nespouštějte jej ve Fabric Spark notebooku.

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

Ověření tokenu

Pomocí isValidToken zkontrolujte, zda je token platný a nevypršel, než s ním zavoláte rozhraní API.

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

Související obsah

  • Last updated on