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 jsou k dispozici v poznámkových blocích Python, PySpark, Scala a R. Příklady na této stránce používají Python jako primární jazyk s ekvivalenty Jazyka Scala a R, kde je veřejné rozhraní API podporuje.

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.
• Redakce tajných hodnot – Výstupy z poznámkového bloku automaticky redigují tajné hodnoty, aby se zabránilo jejich náhodnému odhalení.
• 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:

Python

notebookutils.credentials.help()

Scala

notebookutils.credentials.help()

R

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 není dostupná ve veřejném rozhraní Scala API.
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:

Python

notebookutils.credentials.getToken('audience Key')

Scala

notebookutils.credentials.getToken("audience Key")

R

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 ke čtení a zápisu položek v jezerních domech
  • 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.

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

Poznámka:

Poznámkový blok automaticky redaktuje utajené hodnoty pro zabezpečení. Pokud vytisknete nebo zobrazíte načtené tajemství, zobrazí se ve výstupu místo skutečné hodnoty zamlžený zástupný symbol.

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.
• Neukládejte tajné hodnoty. Spolehněte se na automatickou redakci citlivých údajů ve výstupech poznámkového bloku. Vyhněte se zápisu tajných kódů do souborů nebo jejich předávání jako parametrů poznámkového bloku.
• 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íč

putSecret uloží tajemství do zadaného úložiště Azure Key Vault. Pokud tajný klíč již existuje, hodnota se aktualizuje.

Python

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

Scala

Poznámka:

putSecret není k dispozici ve veřejném rozhraní SCALA API. Poznámkové bloky Python, PySpark nebo R použijte, když potřebujete napsat tajný kód do služby Azure Key Vault z NotebookUtils.

R

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

K zápisu tajných kódů musíte mít příslušná oprávnění (nastavit oprávnění) ve službě Azure Key Vault.

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.

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 není k dispozici ve veřejném rozhraní SCALA API. Ve Scala poznámkových blocích si při potřebě vyžádejte nový token namísto volání tohoto 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")

Související obsah

• NotebookUtils (dříve MSSparkUtils) pro Fabric