Verktyg för NotebookUtils autentiseringsuppgifter för Fabric

Du kan använda verktygen för autentiseringsuppgifter för att hämta åtkomsttoken och hantera hemligheter i Azure Key Vault. Modulen notebookutils.credentials integreras med Microsoft Entra-ID för tokenförvärv och Azure Key Vault för hemlig hantering, så att du kan ansluta till Azure-resurser på ett säkert sätt utan att exponera autentiseringsuppgifter i kod.

Verktyg för autentisering är tillgängliga i anteckningsböcker för Python, PySpark, Scala och R. Exemplen på den här sidan använder Python som primärt språk, med Scala- och R-motsvarigheter som visas där det offentliga API:et stöder dem.

Begränsningar och säkerhet

Innan du använder verktyg för autentiseringsuppgifter bör du vara medveten om dessa begränsningar:

• Förfallodatum för token – Token upphör att gälla efter en period. För långvariga åtgärder implementerar du uppdateringslogik för att begära en ny token innan den upphör att gälla.
• Omfångsbegränsningar för tjänstens huvudnamn – När du kör under ett huvudnamn för tjänsten har token för målgruppen pbi begränsade omfång jämfört med användaridentitet.
• MSAL för fullständigt omfång – Om du behöver det fullständiga Fabric-tjänstomfånget under ett huvudnamn för tjänsten använder du MSAL-autentisering i stället för getToken.
• Hemlig redigering – Notebook-utdata redigerar automatiskt hemliga värden för att förhindra oavsiktlig exponering.
• Key Vault-behörigheter – Du måste ha rätt behörigheter (Hämta för läsning, Ange för skrivning) i Azure Key Vault för att få åtkomst till eller lagra hemligheter.
• Målgruppsändringar – Token-målgruppsomfång kan utvecklas med tiden. Verifiera aktuella omfång i dokumentationen.

Kör följande kommando för att få en översikt över tillgängliga metoder:

notebookutils.credentials.help()

notebookutils.credentials.help()

notebookutils.credentials.help()

I följande tabell visas de tillgängliga metoderna för autentiseringsuppgifter:

Hämta token

getToken returnerar en Microsoft Entra-token för en viss målgrupp. I följande tabell visas tillgängliga målgruppsnycklar:

Kör följande kommando för att hämta token:

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

notebookutils.credentials.getToken("audience Key")

Exempel på tokenanvändning

Du kan använda den returnerade token för att autentisera mot olika Azure-tjänster.

Azure Storage

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

REST-API:er för Power BI och 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 密钥保管库

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

Använd token med Azure SDK

Fabric-notebooks stöder inte DefaultAzureCredential direkt. Du kan använda en anpassad autentiseringsklass som en lösning för att skicka NotebookUtils-token till Azure SDK-klienter.

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

Överväganden

• Tokenomfattningar med pbi som målgrupp kan ändras med tiden.

• När du anropar notebookutils.credentials.getToken("pbi")har den returnerade token ett begränsat omfång om notebook-filen körs under tjänstens huvudnamn. Tokenet har inte det fullständiga Fabric-tjänstomfånget. Om notebook körs under användaridentiteten har token fortfarande det fullständiga Fabric-tjänstomfånget, men detta kan ändras med säkerhetsförbättringar. För att säkerställa att token har hela Fabric-tjänstomfånget använder du MSAL-autentisering i stället för API:et notebookutils.credentials.getToken . Mer information finns i Autentisera med Microsoft Entra-ID.

• Följande omfång är tillgängliga när du anropar notebookutils.credentials.getToken med målgruppsnyckeln pbi under tjänstens huvudnamnsidentitet:

  • Lakehouse.ReadWrite.All – Läs- och skrivåtkomst till Lakehouse-objekt
  • MLExperiment.ReadWrite.All – Läs- och skrivåtkomst till Machine Learning-experimentobjekt
  • MLModel.ReadWrite.All – Läs- och skrivåtkomst till Maskininlärningsmodellobjekt
  • Notebook.ReadWrite.All – Läs- och skrivåtkomst till notebook-objekt
  • SparkJobDefinition.ReadWrite.All – Läs- och skrivåtkomst till Spark-jobbdefinitionsobjekt
  • Workspace.ReadWrite.All – Läs- och skrivåtkomst till arbetsyteobjekt
  • Dataset.ReadWrite.All – Läs- och skrivåtkomst till datauppsättningsobjekt

Hämta hemlighet

getSecret returnerar en Azure Key Vault-hemlighet för en viss Azure Key Vault-slutpunkt och ett hemligt namn. Anropet använder dina aktuella användarautentiseringsuppgifter för att autentisera mot Key Vault.

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

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

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

Du kan hämta flera hemligheter för att skapa anslutningssträngar eller konfigurera tjänster:

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

Använd den fullständigt kvalificerade Key Vault-URL:en i formatet https://<vault-name>.vault.azure.net/. Du måste ha rätt behörighet för att få åtkomst till Key Vault och enskilda hemligheter.

Metodtips för säkerhet

Följ dessa rekommendationer när du arbetar med autentiseringsuppgifter i Fabric Notebooks:

• Lagra alla känsliga värden i Azure Key Vault. Bädda aldrig in autentiseringsuppgifter, anslutningssträngar eller API-nycklar direkt i notebook-kod.
• Logga inte hemliga värden. Förlita dig på den automatiska hemlighetsredigeringen i notebook-utdata. Undvik att skriva hemligheter till filer eller skicka dem som notebook-parametrar.
• Använd rätt målgruppsnyckel. Matcha målgruppsnyckeln med Azure-målresursen så att token bara har de behörigheter som behövs.
• Förstå identitetskontexten. Ta reda på om din notebook-fil körs under användaridentitet eller tjänsthuvudnamn, eftersom de tillgängliga tokenomfattningarna kan skilja sig åt. Testa autentisering i både interaktiva kontexter och pipelinekontexter.
• Hantera förfallodatum för token. Token upphör att gälla. För långvariga åtgärder implementerar du uppdateringslogik för att begära en ny token innan den aktuella upphör att gälla.
• Begränsa åtkomsten till Key Vault. Bevilja endast de minsta behörigheter som krävs till ditt Key Vault. Granska hemlig åtkomst via Azure Key Vault-diagnostikloggar.
• Använd hanterade identiteter när det är möjligt. Hanterade identiteter minskar behovet av att hantera autentiseringsuppgifter manuellt och tillhandahålla ett säkrare autentiseringsflöde.

Lagra hemlighet

putSecret lagrar en hemlighet i det angivna Azure Key Vault. Om hemligheten redan finns uppdateras värdet.

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

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

Du måste ha rätt behörigheter (ange behörighet) i Azure Key Vault för att kunna skriva hemligheter.

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

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

Verifiera token

Använd isValidToken för att kontrollera om en token är giltig och inte har upphört att gälla innan du anropar ett API med den.

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

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

Relaterat innehåll

• NotebookUtils (tidigare MSSparkUtils) för Fabric