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.

De referentiehulpprogramma's zijn beschikbaar in Python-, PySpark-, Scala- en R-notebooks. De voorbeelden op deze pagina gebruiken Python als primaire taal, met Scala- en R-equivalenten die worden weergegeven waar de openbare API deze ondersteunt.

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.
  • Geheime redactie – Notebook-uitvoer redigeert automatisch geheime waarden om onbedoelde blootstelling te voorkomen.
  • 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 is niet beschikbaar in de openbare Scala-API.
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 Machine Learning Experiment-items
    • MLModel.ReadWrite.All – Lees- en schrijftoegang tot Machine Learning-modelitems
    • Notebook.ReadWrite.All – Lees- en schrijftoegang tot notitieblokitems
    • SparkJobDefinition.ReadWrite.All – Lees- en schrijftoegang tot Spark-taakdefinitie-items
    • Workspace.ReadWrite.All – Lees- en schrijftoegang tot werkruimte-items
    • Dataset.ReadWrite.All – Lees- en schrijftoegang tot gegevenssetitems

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

Opmerking

Notebook voert automatisch geheime waarden voor beveiliging op. Als u een opgehaald geheim afdrukt of weergeeft, wordt in de uitvoer een gecensureerde tijdelijke aanduiding weergegeven in plaats van de werkelijke waarde.

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.
  • Leg geen geheime waarden vast. Vertrouw op de automatische verwijdering van geheimen in notebook-uitvoer. Schrijf geen geheimen naar bestanden of geef ze door als notebookparameters.
  • 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

putSecret slaat een geheim op in de opgegeven Azure Key Vault. Als het geheim al bestaat, wordt de waarde bijgewerkt.

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

U moet over de juiste machtigingen (machtiging instellen) beschikken voor Azure Key Vault om geheimen te kunnen schrijven.

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

  • Last updated on