Utilitaires d'identifiants NotebookUtils pour Fabric

Vous pouvez utiliser les utilitaires d’informations d’identification pour obtenir des jetons d’accès et gérer les secrets dans Azure Key Vault. Le notebookutils.credentials module s’intègre avec l’ID Microsoft Entra pour l’acquisition de jetons et Azure Key Vault pour la gestion des secrets. Vous pouvez donc vous connecter en toute sécurité aux ressources Azure sans exposer les informations d’identification dans le code.

Les utilitaires d'authentification sont disponibles dans les blocs-notes Python, PySpark, Scala et R. Les exemples de cette page utilisent Python comme langage principal, avec des équivalents Scala et R indiqués où l’API publique les prend en charge.

Important

Ne codez jamais en dur les secrets ou les informations d’identification directement dans le code du notebook. Utilisez toujours Azure Key Vault pour stocker des valeurs sensibles et les récupérer au moment de l’exécution avec notebookutils.credentials.getSecret.

Contraintes et sécurité

Avant d’utiliser les utilitaires d’informations d’identification, tenez compte de ces contraintes :

  • Expiration du jeton : les jetons expirent après une période. Pour les opérations de longue durée, implémentez la logique d’actualisation pour demander un nouveau jeton avant l’expiration.
  • Limitations des étendues du service principal : lorsqu'il est exécuté sous un service principal, les jetons pour l’audience pbi ont des étendues restreintes par rapport à l’identité de l’utilisateur.
  • MSAL pour l’étendue complète : si vous avez besoin de l’étendue complète du service Fabric sous un principal de service, utilisez l’authentification MSAL au lieu de getToken.
  • Redaction des secrets : le bloc-notes génère automatiquement des valeurs secrètes pour empêcher l’exposition accidentelle.
  • Autorisations Key Vault : vous devez disposer des autorisations appropriées (Obtenir pour la lecture, Définir pour l’écriture) sur Azure Key Vault pour accéder ou stocker des secrets.
  • Changements d’audience : les périmètres d’audience de jeton peuvent évoluer au fil du temps. Vérifiez les étendues actuelles dans la documentation.

Exécutez la commande suivante pour obtenir une vue d’ensemble des méthodes disponibles :

notebookutils.credentials.help()

Le tableau suivant répertorie les méthodes d’informations d’identification disponibles :

Méthode Signature Description
getToken getToken(audience: String): String Retourne un jeton Microsoft Entra pour le public spécifié.
getSecret getSecret(akvName: String, secret: String): String Retourne la valeur d’un secret à partir du coffre de clés Azure spécifié.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Stocke un secret dans le Azure Key Vault spécifié. Cette méthode n’est pas disponible dans l’API Scala publique.
isValidToken isValidToken(token: String): Boolean Vérifie si le jeton donné est valide et n’a pas expiré. Cette méthode n’est pas disponible dans l’API Scala publique.

Obtenir un jeton

getToken retourne un jeton Microsoft Entra pour une audience donnée. Le tableau suivant présente les clés d’audience actuellement disponibles :

Clé d’audience Ressource Cas d’utilisation
storage Azure Storage Accéder à ADLS Gen2 et au stockage d’objets blob.
pbi Power BI Appeler des API REST Power BI et Fabric
keyvault Azure Key Vault Récupérer les secrets de Key Vault
kusto Base de données Synapse RTA KQL Se connecter à l’Explorateur de données Azure

Exécutez la commande suivante pour obtenir le jeton :

notebookutils.credentials.getToken('audience Key')

Exemples d’utilisation des jetons

Vous pouvez utiliser le jeton retourné pour vous authentifier auprès de différents services Azure.

Azure Storage

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

API REST Power BI et 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')

Utiliser des jetons avec le Kit de développement logiciel (SDK) Azure

Les blocs-notes Fabric ne prennent pas en charge DefaultAzureCredential directement. Vous pouvez utiliser une classe d’informations d’identification personnalisée comme solution de contournement pour passer des jetons NotebookUtils aux clients du Kit de développement logiciel (SDK) Azure.

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

Conseil / Astuce

Les jetons expirent après une période de temps. Si votre bloc-notes exécute de longues opérations, implémentez la logique d’actualisation pour demander un nouveau jeton avant l’expiration du jeton actuel.

Considérations

  • Les portées de jetons avec pbi comme auditoire peuvent changer au fil du temps.

  • Lorsque vous appelez notebookutils.credentials.getToken("pbi"), si le notebook s'exécute sous un principal de service, le jeton retourné a une étendue limitée. Le jeton n’a pas l’étendue complète du service Fabric. Si le notebook s’exécute sous l’identité de l’utilisateur, le jeton conserve une portée complète du service Fabric, mais cela pourrait changer à la suite d'améliorations de sécurité. Pour vous assurer que le jeton a l’étendue complète du service Fabric, utilisez l’authentification MSAL au lieu de l’API notebookutils.credentials.getToken . Pour plus d’informations, consultez S’authentifier avec l’ID Microsoft Entra.

  • Les périmètres suivants sont disponibles lorsque vous appelez notebookutils.credentials.getToken avec la clé d’audience pbi sous l’identité de l’entité principale du service :

    • Lakehouse.ReadWrite.All – Accès en lecture et écriture aux éléments Lakehouse
    • MLExperiment.ReadWrite.All – Accès en lecture et écriture aux éléments d’expérience Machine Learning
    • MLModel.ReadWrite.All – Accès en lecture et écriture aux éléments du modèle Machine Learning
    • Notebook.ReadWrite.All – Accès en lecture et écriture aux éléments du bloc-notes
    • SparkJobDefinition.ReadWrite.All – Accès en lecture et écriture aux éléments Spark Job Definition
    • Workspace.ReadWrite.All – Accès en lecture et écriture aux éléments de l’espace de travail
    • Dataset.ReadWrite.All – Accès en lecture et écriture aux éléments du jeu de données

Conseil / Astuce

Si vous avez besoin d’accéder à des services Fabric supplémentaires ou à des autorisations plus larges sous un principal de service, utilisez MSAL pour Python pour s’authentifier directement avec l’étendue complète du service Fabric au lieu de vous appuyer sur getToken("pbi").

Obtenir un secret

getSecret retourne un secret Azure Key Vault pour un point de terminaison Azure Key Vault et un nom de secret donnés. L’appel utilise vos informations d’identification utilisateur actuelles pour s’authentifier auprès de Key Vault.

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

Vous pouvez récupérer plusieurs secrets pour générer des chaînes de connexion ou configurer des services :

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

Note

Les sorties du notebook masquent automatiquement les valeurs secrètes pour la sécurité. Si vous imprimez ou affichez un secret récupéré, la sortie affiche un espace réservé masqué au lieu de la valeur réelle.

Utilisez l'URL complète de Key Vault au format https://<vault-name>.vault.azure.net/. Vous devez disposer des autorisations appropriées pour accéder au coffre de clés et aux secrets individuels.

Bonnes pratiques de sécurité

Suivez ces recommandations lorsque vous utilisez des informations d’identification dans les notebooks Fabric :

  • Stockez toutes les valeurs sensibles dans Azure Key Vault. N’incorporez jamais d’informations d’identification, de chaînes de connexion ou de clés API directement dans le code du notebook.
  • Ne consignez pas les valeurs de secret. Utilisez le masquage automatique des secrets dans les résultats du notebook. Évitez d’écrire des secrets dans des fichiers ou de les transmettre en tant que paramètres de notebook.
  • Utilisez la clé d’audience correcte. Associez la clé d'audience à la ressource Azure cible pour que le jeton ne dispose que des autorisations nécessaires.
  • Comprendre le contexte d’identité. Déterminez si votre bloc-notes s’exécute sous l’identité de l’utilisateur ou un principal de service, car les étendues de jeton disponibles peuvent différer. Testez l’authentification dans des contextes interactifs et de pipeline.
  • Gérer l’expiration du jeton. Les jetons expirent. Pour les opérations de longue durée, implémentez la logique d’actualisation pour demander un nouveau jeton avant l’expiration du jeton actuel.
  • Limitez l’accès Key Vault. Accordez uniquement les autorisations minimales requises à votre coffre de clés. Effectuez un audit de l'accès aux secrets via les journaux de diagnostic de Key Vault d'Azure.
  • Utilisez des identités managées lorsque cela est possible. Les identités managées réduisent la nécessité de gérer les informations d’identification manuellement et fournissent un flux d’authentification plus sécurisé.

Configurer un secret

putSecret stocke un secret dans le Azure Key Vault spécifié. Si le secret existe déjà, la valeur est mise à jour.

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

Vous devez disposer des autorisations appropriées (Définir l’autorisation) sur Azure Key Vault pour écrire des secrets.

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

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

Valider un jeton

Permet isValidToken de vérifier si un jeton est valide et non expiré avant d’appeler une API avec elle.

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

Contenu connexe

  • Last updated on