Hulpprogramma's voor referentiebeheer in notebookUtils voor Fabric

U kunt de hulpprogramma's voor referenties gebruiken om toegangstokens op te halen en geheimen in Azure Key Vault te beheren. De notebookutils.credentials module kan worden geïntegreerd met Microsoft Entra ID voor het verkrijgen van tokens en Azure Key Vault voor geheimbeheer, zodat u veilig verbinding kunt maken met Azure-resources zonder referenties in code weer te geven.

Je kunt de inloggegevensprogramma's gebruiken in Python-notebooks en Fabric Spark-notebooks. In Fabric Spark-notebooks kun je PySpark, Scala of R gebruiken. De beschikbaarheid van methoden verschilt per notebook-runtime en API. Bijvoorbeeld, putSecret werkt alleen in Python-notebooks, die de Python-runtime gebruiken. Spark-notebooks ondersteunen het niet, zelfs niet als ze Python-code draaien met PySpark. Spark-notebooks die Scala of R gebruiken, ondersteunen het ook niet.

De volgende voorbeelden gebruiken Python als primaire taal. Scala- en R-equivalenten verschijnen waar de notebook-runtime en de publieke API de methode ondersteunen.

Belangrijk

Codeer geheimen of referenties nooit rechtstreeks in notebookcode. Gebruik Altijd Azure Key Vault om gevoelige waarden op te slaan en op te halen tijdens runtime met notebookutils.credentials.getSecret.

Beperkingen en veiligheid

Voordat u hulpprogramma's voor referenties gebruikt, moet u rekening houden met deze beperkingen:

  • Verloop van tokens: tokens verlopen na een periode. Implementeer voor langlopende bewerkingen vernieuwingslogica om een nieuw token aan te vragen voordat deze verloopt.
  • Beperkingen voor het bereik van de service-principal : bij uitvoering onder een service-principal hebben tokens voor de pbi doelgroep beperkte bereiken vergeleken met de gebruikersidentiteit.
  • MSAL voor volledig bereik : als u het volledige Fabric-servicebereik onder een service-principal nodig hebt, gebruikt u MSAL-verificatie in plaats van getToken.
  • Maskering van geheimen – Notebookuitvoer probeert de oorspronkelijke waarde van het geheim te maskeren wanneer code deze rechtstreeks afdrukt of weergeeft. Deze zo goed mogelijke beveiliging vermindert onbedoelde openbaarmaking, ook tijdens het delen van uw scherm. Het is geen beveiligingsgrens. Na het ophalen ontvangt de geautoriseerde notebookcode plattekst en kan deze de geheime inhoud of inhoud die van het geheim is afgeleid verwerken, omzetten of openbaar maken.
  • Key Vault-machtigingen : u moet over de juiste machtigingen beschikken (Voor lezen, Instellen voor schrijven) in Azure Key Vault om toegang te krijgen tot geheimen of op te slaan.
  • Wijzigingen in het tokenpubliek – bereik van tokens kan zich in de loop van de tijd ontwikkelen. Controleer de huidige toegangsrechten in de documentatie.

Voer de volgende opdracht uit om een overzicht te krijgen van de beschikbare methoden:

notebookutils.credentials.help()

De volgende tabel lijst de beschikbare authenticatiemethoden op:

Methode Signature Beschrijving
getToken getToken(audience: String): String Hiermee wordt een Microsoft Entra-token geretourneerd voor de opgegeven doelgroep.
getSecret getSecret(akvName: String, secret: String): String Retourneert de waarde van een geheim uit de opgegeven Azure Key Vault.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Slaat een geheim op in de opgegeven Azure Key Vault. Deze methode werkt alleen in notebooks die de Python-runtime gebruiken. Spark-notebooks ondersteunen het niet, zelfs niet als ze Python-code draaien met PySpark. Spark-notebooks die Scala of R gebruiken, ondersteunen het ook niet.
isValidToken isValidToken(token: String): Boolean Controleert of het opgegeven token geldig is en niet is verlopen. Deze methode is niet beschikbaar in de openbare Scala-API.

Token ophalen

getToken retourneert een Microsoft Entra-token voor een bepaalde doelgroep. In de volgende tabel ziet u de momenteel beschikbare doelgroepsleutels:

Doelgroepsleutel Hulpbron Gebruiksituatie
storage Azure-opslag Toegang tot ADLS Gen2 en Blob Storage
pbi Power BI REST API's voor Power BI en Fabric aanroepen
keyvault Azure Key Vault Key Vault-geheimen ophalen
kusto Synapse RTA KQL DB Verbinding maken met Azure Data Explorer

Voer de volgende opdracht uit om het token op te halen:

notebookutils.credentials.getToken('audience Key')

Voorbeelden van tokengebruik

U kunt het geretourneerde token gebruiken om te verifiëren bij verschillende Azure-services.

Azure-opslag

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

REST API's voor Power BI en 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')

Tokens gebruiken met de Azure SDK

Fabric-notebooks ondersteunen niet rechtstreeks DefaultAzureCredential. U kunt een aangepaste referentieklasse gebruiken als tijdelijke oplossing om NotebookUtils-tokens door te geven aan Azure SDK-clients.

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

Aanbeveling

Tokens verlopen na een bepaalde periode. Als uw notebook lange bewerkingen uitvoert, implementeert u vernieuwingslogica om een nieuw token aan te vragen voordat het huidige token verloopt.

Overwegingen

  • Tokenbereiken met pbi als doelgroep kunnen in de loop van de tijd veranderen.

  • Wanneer u aanroept notebookutils.credentials.getToken("pbi"), heeft het geretourneerde token een beperkt bereik als het notebook wordt uitgevoerd onder een service-principal. Het token heeft niet het volledige Fabric-servicebereik. Als het notebook wordt uitgevoerd onder de gebruikersidentiteit, heeft het token nog steeds het volledige servicebereik van Fabric, maar dit kan veranderen met beveiligingsverbeteringen. Gebruik MSAL-verificatie in plaats van de notebookutils.credentials.getToken API om ervoor te zorgen dat het token het volledige Fabric-servicebereik heeft. Zie Verifiëren met Microsoft Entra ID voor meer informatie.

  • De volgende scopes zijn beschikbaar wanneer u notebookutils.credentials.getToken met de audience-sleutel pbi aanroept onder de service-principal-identiteit.

    • Lakehouse.ReadWrite.All – Lees- en schrijftoegang tot lakehouse-items
    • MLExperiment.ReadWrite.All – Lees- en schrijftoegang tot experimentele items
    • MLModel.ReadWrite.All – Lees- en schrijftoegang tot ML-modelitems
    • Notebook.ReadWrite.All – Lees- en schrijftoegang tot notitieboekitems
    • SparkJobDefinition.ReadWrite.All – Lees- en schrijftoegang tot onderdelen van Spark-taakdefinities
    • Workspace.ReadWrite.All – Lees- en schrijftoegang tot werkruimtes
    • Dataset.ReadWrite.All – Lees- en schrijftoegang tot semantische modelitems

Aanbeveling

Als u toegang nodig hebt tot aanvullende Fabric-services of bredere machtigingen onder een service-principal, gebruikt u MSAL voor Python om rechtstreeks te verifiëren met het volledige Fabric-servicebereik in plaats van erop getToken("pbi")te vertrouwen.

Geheim ophalen

getSecret retourneert een Azure Key Vault-geheim voor een bepaald Azure Key Vault-eindpunt en een geheime naam. De aanroep maakt gebruik van uw huidige gebruikersreferenties om te verifiëren bij Key Vault.

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

U kunt meerdere geheimen ophalen om verbindingsreeksen te bouwen of services te configureren:

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

Belangrijk

Na succesvolle opvraging ontvangt de geautoriseerde notitieboekcode de geheime waarde als platte tekst. Notebook-uitvoer probeert de oorspronkelijke geheime waarde te maskeren wanneer code deze direct afdrukt of weergeeft.

Deze zo goed mogelijke beveiliging vermindert onbedoelde openbaarmaking in de uitvoer van notebooks, ook tijdens het delen van uw scherm. Het is geen beveiligingsgrens en voorkomt geen verwerking, transformatie of openbaarmaking van geheim-afgeleide content.

Gebruik de volledig gekwalificeerde Key Vault-URL in de indeling https://<vault-name>.vault.azure.net/. U moet over de juiste machtigingen beschikken om toegang te krijgen tot de Sleutelkluis en de afzonderlijke geheimen.

Aanbevolen procedures voor beveiliging

Volg deze aanbevelingen wanneer u werkt met referenties in Fabric-notebooks:

  • Sla alle gevoelige waarden op in Azure Key Vault. Sluit nooit referenties, verbindingsreeksen of API-sleutels rechtstreeks in notebookcode in.
  • Onthullen geen geheime waarden. Druk geheime gegevens niet af, log ze niet, schrijf ze niet weg naar bestanden en geef ze niet door als notebookparameters. Output redaction probeert de oorspronkelijke waarde te beschermen in directe notitieboekuitvoer. Het voorkomt niet dat geheime inhoud wordt onthuld.
  • Gebruik de juiste doelgroepsleutel. Koppel de doelgroepsleutel aan de Azure-doelresource, zodat het token alleen de benodigde machtigingen heeft.
  • Inzicht in de identiteitscontext. Weet of uw notebook wordt uitgevoerd onder gebruikersidentiteit of een service-principal, omdat de beschikbare tokenbereiken kunnen verschillen. Testen van authenticatie in zowel interactieve als pijplijncontexten.
  • Verloopdatum van token verwerken. Tokens verlopen. Voor langlopende bewerkingen implementeert u vernieuwingslogica om een nieuw token aan te vragen voordat het huidige token verloopt.
  • Toegang tot Key Vault beperken. Verken alleen de minimaal vereiste machtigingen voor uw Key Vault. Geheime toegang controleren via diagnostische logboeken van Azure Key Vault.
  • Gebruik indien mogelijk beheerde identiteiten. Beheerde identiteiten verminderen de noodzaak om referenties handmatig te beheren en een veiligere verificatiestroom te bieden.

Geheim plaatsen

putSecretslaat een geheim op of werkt het bij in de gespecificeerde Azure Key Vault. Het werkt alleen in notebooks die de Python-runtime gebruiken.

Belangrijk

Spark-notebooks ondersteunen putSecretniet, zelfs niet als ze Python-code draaien met PySpark. Spark-notebooks die Scala of R gebruiken, ondersteunen het ook niet. Gebruik een Python-notebook, dat de Python-runtime gebruikt.

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

Om geheimen te schrijven, heb je de juiste permissies (Set permission) nodig op de Azure Key Vault. Voer het volgende voorbeeld alleen uit in een notebook dat de Python-runtime gebruikt. Voer het niet uit in een Fabric Spark-notebook.

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

Token valideren

Gebruik isValidToken dit om te controleren of een token geldig is en niet is verlopen voordat u er een API mee aanroept.

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

Verwante inhoud

  • Laatst bijgewerkt om