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.

Vous pouvez utiliser les utilitaires d’informations d’identification dans les notebooks Python et les notebooks Fabric Spark. Dans les notebooks Fabric Spark, vous pouvez utiliser PySpark, Scala ou R. La disponibilité des méthodes varie selon l’exécution et l’API du notebook. Par exemple, putSecret fonctionne uniquement dans les notebooks Python, qui utilisent l’environnement d’exécution Python. Les notebooks Spark ne le supportent pas, même lorsqu'ils exécutent du code Python avec PySpark. Les notebooks Spark qui utilisent Scala ou R ne le supportent pas non plus.

Les exemples suivants utilisent Python comme langage principal. Les équivalents Scala et R apparaissent lorsque le temps d’exécution du notebook et l’API publique supportent la méthode.

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.
  • Masquage des secrets – Les sorties du notebook tentent de masquer la valeur d’origine du secret lorsque le code l’imprime ou l’affiche directement. Cette protection optimale réduit la divulgation accidentelle, y compris lors du partage d’écran. Ce n’est pas une frontière de sécurité. Après récupération, le code du carnet autorisé reçoit du texte clair et peut traiter, transformer ou divulguer le contenu secret ou dérivé du secret.
  • 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 ne fonctionne que dans les notebooks utilisant l’exécution Python. Les notebooks Spark ne le supportent pas, même lorsqu'ils exécutent du code Python avec PySpark. Les notebooks Spark utilisant Scala ou R ne le supportent pas non plus.
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 stockage Azure 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.

stockage Azure

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 en écriture aux éléments du lakehouse
    • MLExperiment.ReadWrite.All – Accès en lecture et écriture aux éléments expérimentaux
    • MLModel.ReadWrite.All – Accès en lecture et écriture aux items du modèle ML
    • Notebook.ReadWrite.All – Accès à la lecture et à l’écriture aux éléments du carnet
    • SparkJobDefinition.ReadWrite.All – Accès en lecture et écriture aux éléments de définition de tâches Spark
    • Workspace.ReadWrite.All – Accès en lecture et écriture aux espaces de travail
    • Dataset.ReadWrite.All – Accès en lecture et écriture aux éléments du modèle sémantique

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

Important

Après une récupération réussie, le code du carnet autorisé reçoit la valeur secrète en texte clair. La sortie du notebook tente de masquer la valeur secrète d’origine lorsque le code l’imprime ou l’affiche directement.

Cette protection, appliquée dans la mesure du possible, réduit le risque de divulgation accidentelle dans les sorties du notebook, y compris lors du partage d’écran. Ce n’est pas une frontière de sécurité et n’empêche pas le traitement, la transformation ou la divulgation de contenus dérivés de secrets.

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 divulguez pas de valeurs secrètes. N’imprimez pas ni ne consignez les secrets, ne les écrivez pas dans des fichiers, ni ne les passez comme paramètres de carnet. Le masquage de la sortie vise à protéger la valeur d’origine dans la sortie directe du notebook. Elle n’empêche pas la divulgation de contenu dérivé de données secrètes.
  • 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

putSecretstocke ou met à jour un secret dans le Azure Key Vault spécifié. Cela ne fonctionne que dans les notebooks qui utilisent le runtime Python.

Important

Les notebooks Spark ne prennent pas en charge putSecret, même lorsqu'ils exécutent du code Python avec PySpark. Les notebooks Spark utilisant Scala ou R ne le supportent pas non plus. Utilisez un notebook Python, qui utilise l’environnement d’exécution Python.

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

Pour écrire des secrets, il faut les permissions appropriées (Définir la permission) sur Azure Key Vault. Exécutez l’exemple suivant uniquement dans un notebook utilisant l’exécution Python. Ne l'utilisez pas dans un carnet Fabric Spark.

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

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