NotebookUtils hitelesítési segédprogramok a Fabrichez

A hitelesítő adatok segédprogramjaival hozzáférési jogkivonatokat szerezhet be, és titkos kulcsokat kezelhet az Azure Key Vaultban. A notebookutils.credentials modul integrálható a Microsoft Entra-azonosítóval a jogkivonatok beszerzéséhez és az Azure Key Vault titkos kulcskezeléshez, így biztonságosan csatlakozhat az Azure-erőforrásokhoz anélkül, hogy hitelesítő adatokat ad meg a kódban.

A hitelesítő adatok segédprogramjai Python-, PySpark-, Scala- és R-jegyzetfüzetekben érhetők el. Az ezen a lapon szereplő példák a Pythont használják elsődleges nyelvként, és a Scala és az R-ekvivalensek azt mutatják, hogy hol támogatja őket a nyilvános API.

Fontos

Soha ne kódoljon titkos kulcsokat vagy hitelesítő adatokat közvetlenül a jegyzetfüzet kódjában. Mindig használja az Azure Key Vaultot a bizalmas értékek tárolására és lekérésére futásidőben a következővel notebookutils.credentials.getSecret: .

Korlátozások és biztonság

A hitelesítő adatok segédprogramjainak használata előtt vegye figyelembe az alábbi korlátozásokat:

  • Jogkivonat lejárata – A jogkivonatok egy időszak után lejárnak. Hosszú ideig futó műveletek esetén implementáljon frissítési logikát egy új jogkivonat lekéréséhez a lejárat előtt.
  • Szolgáltatásnév hatókörének korlátozásai – Ha szolgáltatásnév alatt fut, a célközönség jogkivonatai korlátozott hatókörrel rendelkeznek a pbi felhasználói identitáshoz képest.
  • MSAL a teljes hatókörért – Ha egy szolgáltatásnév alatt szüksége van a teljes Fabric szolgáltatástartományra, használja az MSAL-hitelesítést getToken helyett.
  • Titkos adatok elrejtése – A jegyzetfüzet kimenetei automatikusan elfedik a titkos értékeket, hogy elkerüljék a véletlen kiszivárogtatást.
  • Key Vault-engedélyek – A titkos kódok eléréséhez vagy tárolásához megfelelő engedélyekkel kell rendelkeznie az Azure Key Vaultban (olvasáshoz, íráshoz beállítva).
  • Közönségváltozások – A token közönség hatókörei idővel fejlődhetnek. Ellenőrizze az aktuális hatóköröket a dokumentációban.

Futtassa a következő parancsot az elérhető módszerek áttekintéséhez:

notebookutils.credentials.help()

Az alábbi táblázat a rendelkezésre álló hitelesítő adatokat sorolja fel:

Módszer Signature Leírás
getToken getToken(audience: String): String Egy Microsoft Entra-jogkivonatot ad vissza a megadott célközönség számára.
getSecret getSecret(akvName: String, secret: String): String Egy titkos kód értékét adja vissza a megadott Azure Key Vaultból.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Titkos kulcsot tárol a megadott Azure Key Vaultban. Ez a módszer nem érhető el a nyilvános Scala API-ban.
isValidToken isValidToken(token: String): Boolean Ellenőrzi, hogy a megadott jogkivonat érvényes-e, és nem járt-e le. Ez a módszer nem érhető el a nyilvános Scala API-ban.

Token lekérése

getToken Egy Microsoft Entra-jogkivonatot ad vissza egy adott célközönség számára. Az alábbi táblázat a jelenleg elérhető célközönségkulcsokat mutatja be:

Célközönségkulcs erőforrás Felhasználási eset
storage Azure Storage Hozzáférés az ADLS Gen2-hez és a Blob Storage-hoz
pbi Power BI Power BI és Fabric REST API-k meghívása
keyvault Azure Key Vault Key Vault-titkos kulcsok lekérése
kusto Synapse RTA KQL DB Csatlakozás az Azure Data Explorerhez

Futtassa a következő parancsot a jogkivonat lekéréséhez:

notebookutils.credentials.getToken('audience Key')

Token használati példák

A visszaadott jogkivonattal különböző Azure-szolgáltatásokon végezhet hitelesítést.

Azure Storage

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

Power BI és Fabric REST API-k

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

Az Azure SDK tokenjeinek használata

A szövet jegyzetfüzetek nem támogatják közvetlenül a DefaultAzureCredential-t. Áthidaló megoldásként használhat egyéni hitelesítő osztályt a NotebookUtils-jogkivonatok Azure SDK-ügyfeleknek való átadásához.

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

Jótanács

A tokenek egy idő után lejárnak. Ha a notebook hosszú műveleteket futtat, valósítson meg egy frissítési logikát, amely új jogkivonatot kér az aktuális lejárat előtt.

Megfontolások

  • A pbi nézőként meghatározott token hatókörök idővel változhatnak.

  • Híváskor notebookutils.credentials.getToken("pbi")a visszaadott jogkivonat korlátozott hatókörrel rendelkezik, ha a jegyzetfüzet szolgáltatásnév alatt fut. A token nem rendelkezik a Fabric szolgáltatás teljes hatókörével. Ha a jegyzetfüzet a felhasználói identitás alatt fut, a jogkivonat továbbra is a teljes Fabric-szolgáltatás hatókörrel rendelkezik, de ez a biztonsági fejlesztésekkel változhat. Annak érdekében, hogy a token teljes Fabric szolgáltatási hatókörrel rendelkezzen, használjon MSAL-hitelesítést az notebookutils.credentials.getToken API helyett. További információ: Hitelesítés a Microsoft Entra-azonosítóval.

  • A következő hatókörök érhetők el, ha a célközönség kulccsal notebookutils.credentials.getToken hívja pbi meg a szolgáltatásnév identitása alatt:

    • Lakehouse.ReadWrite.All – Olvasás és írás hozzáférése tóházi tárgyakhoz
    • MLExperiment.ReadWrite.All – Olvasási és írási hozzáférés kísérleti tárgyakhoz
    • MLModel.ReadWrite.All – Olvasási és írási hozzáférés ML modell elemekhez
    • Notebook.ReadWrite.All – Olvasási és írási hozzáférés jegyzetfüzetek tárgyaihoz
    • SparkJobDefinition.ReadWrite.All – Olvasni és írni a hozzáférést a Spark munkadefiníciós elemekhez
    • Workspace.ReadWrite.All – Olvasási és írási hozzáférés a munkaterületekhez
    • Dataset.ReadWrite.All – Olvasási és írási hozzáférés szemantikai modellelemekhez

Jótanács

Ha további Fabric-szolgáltatásokhoz vagy szélesebb körű engedélyekhez szeretne hozzáférni egy szolgáltatásnév alatt, az MSAL for Python használatával közvetlenül a teljes Fabric-szolgáltatás hatókörével hitelesíthet ahelyett, hogy azokra getToken("pbi")támaszkodhat.

Titkos kód lekérése

getSecret Egy Azure Key Vault-titkos kulcsot ad vissza egy adott Azure Key Vault-végponthoz és titkos névhez. A hívás az aktuális felhasználói hitelesítő adatokkal hitelesíti a Key Vaultot.

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

A kapcsolati sztringek létrehozásához vagy a szolgáltatások konfigurálásához több titkos kulcs is lekérhető:

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

Megjegyzés:

A jegyzetfüzet kimenetei automatikusan módosítják a titkos kódok értékeit a biztonság érdekében. Ha kinyomtat vagy megjelenít egy lekért titkot, a kimenet a tényleges érték helyett egy kitakart helyőrzőt mutat.

Használja a kulcstár teljesen érvényesített URL-címét a következő formátumban: https://<vault-name>.vault.azure.net/. A Key Vault és az egyes titkos kódok eléréséhez megfelelő engedélyekkel kell rendelkeznie.

Ajánlott biztonsági eljárások

Kövesse az alábbi ajánlásokat, amikor a Fabric-jegyzetfüzetekben hitelesítő adatokkal dolgozik:

  • Az összes bizalmas érték tárolása az Azure Key Vaultban. Soha ne ágyazza be közvetlenül a jegyzetfüzet kódjába a hitelesítő adatokat, kapcsolati sztringeket vagy API-kulcsokat.
  • Ne naplózza a titkos kódok értékeit. A jegyzetfüzet kimeneteiben az automatikus titkos kódátadásra támaszkodhat. Ne írjon titkos kulcsokat a fájloknak, vagy adja át őket jegyzetfüzet-paraméterként.
  • Használja a megfelelő célközönségkulcsot. Célozza meg az Azure-erőforrást a megfelelő jogosultsági kulccsal, így a token csak a szükséges engedélyeket tartalmazza.
  • Az identitás kontextusának megismerése. Tudja meg, hogy a jegyzetfüzet felhasználói azonosító vagy szolgáltatásazonosító alatt fut-e, mert a rendelkezésre álló jogkivonat-hatókörök eltérhetnek. Tesztelje a hitelesítést interaktív és folyamatkörnyezetekben is.
  • A tokent lejáratának kezelése. A tokenek lejárnak. Hosszú ideig futó műveletek esetén a frissítési logikát implementálva kérjen új jogkivonatot az aktuális lejárata előtt.
  • A Key Vault hozzáférésének korlátozása. Csak a minimálisan szükséges engedélyeket adja meg a Key Vaulthoz. Titkos kódokhoz való hozzáférés naplózása az Azure Key Vault diagnosztikai naplóiban.
  • Ha lehetséges, használjon felügyelt identitásokat. A felügyelt identitások csökkentik a hitelesítő adatok manuális kezelését, és biztonságosabb hitelesítési folyamatot biztosítanak.

Titkos kód elhelyezése

putSecret titkos kulcsokat tárol a megadott Azure Key Vaultban. Ha a titkos kód már létezik, az érték frissül.

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

Titkos kulcsok írásához megfelelő engedélyekkel (beállítási engedéllyel) kell rendelkeznie az Azure Key Vaultban.

vault_url = "https://myvault.vault.azure.net/"

notebookutils.credentials.putSecret(vault_url, "api-key", "my-secret-api-key-value")

Token érvényesítése

Használja a isValidToken-t annak ellenőrzésére, hogy érvényes-e és nem járt-e le a jogkivonat, mielőtt meghív egy API-t vele.

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

Kapcsolódó tartalom

  • Last updated on