Utilidades de credenciales NotebookUtils para Fabric

Puede usar las utilidades de credenciales para obtener tokens de acceso y administrar secretos en Azure Key Vault. El notebookutils.credentials módulo se integra con Microsoft Entra ID para la adquisición de tokens y Azure Key Vault para la administración de secretos, por lo que puede conectarse a recursos de Azure de forma segura sin exponer credenciales en el código.

Las utilidades de credenciales están disponibles en cuadernos de Python, PySpark, Scala y R. Los ejemplos de esta página usan Python como lenguaje principal, con los equivalentes de Scala y R que se muestran donde la API pública las admite.

Importante

Nunca codifique de forma rígida secretos o credenciales directamente en el código del cuaderno. Use Siempre Azure Key Vault para almacenar valores confidenciales y recuperarlos en tiempo de ejecución con notebookutils.credentials.getSecret.

Restricciones y seguridad

Antes de usar las utilidades de credenciales, tenga en cuenta estas restricciones:

  • Expiración del token : los tokens expiran después de un período. Para las operaciones de larga duración, implemente la lógica de actualización para solicitar un nuevo token antes de la expiración.
  • Limitaciones del ámbito de la entidad de servicio: al ejecutarse en una entidad de servicio, los tokens para la pbi audiencia tienen ámbitos restringidos en comparación con la identidad del usuario.
  • MSAL para ámbito completo – si necesita el ámbito completo del servicio de Fabric bajo una entidad de servicio, use la autenticación MSAL en lugar de getToken.
  • Redacción secreta : las salidas del cuaderno redactan automáticamente los valores secretos para evitar la exposición accidental.
  • Permisos de Key Vault : debe tener los permisos adecuados (Obtener para leer, Establecer para escribir) en Azure Key Vault para acceder o almacenar secretos.
  • Cambios de audiencia: los ámbitos de audiencia de tokens pueden evolucionar con el tiempo. Compruebe los ámbitos actuales en la documentación.

Ejecute el siguiente comando para obtener información general sobre los métodos disponibles:

notebookutils.credentials.help()

En la tabla siguiente se enumeran los métodos de credenciales disponibles:

Método Signature Descripción
getToken getToken(audience: String): String Devuelve un token de Microsoft Entra para la audiencia especificada.
getSecret getSecret(akvName: String, secret: String): String Devuelve el valor de un secreto del almacén de claves de Azure especificado.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Almacena un secreto en el almacén de claves de Azure especificado. Este método no está disponible en la API de Scala pública.
isValidToken isValidToken(token: String): Boolean Comprueba si el token especificado es válido y no ha expirado. Este método no está disponible en la API de Scala pública.

Obtener el token

getToken devuelve un token de Microsoft Entra para una audiencia determinada. En la tabla siguiente se muestran las claves de audiencia disponibles actualmente:

Clave de audiencia Recurso Caso de uso
storage Azure Storage Acceso a ADLS Gen2 y Blob Storage
pbi Power BI Llamada a las API REST de Power BI y Fabric
keyvault Azure Key Vault Recuperación de secretos de Key Vault
kusto Base de datos KQL de Synapse RTA Conectarse al Explorador de datos de Azure

Ejecute el siguiente comando para obtener el token:

notebookutils.credentials.getToken('audience Key')

Ejemplos de uso de tokens

Puede usar el token devuelto para autenticarse en varios servicios de Azure.

Azure Storage

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

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

Uso de tokens con el SDK de Azure

Los cuadernos de Fabric no admiten DefaultAzureCredential directamente. Puede usar una clase de credenciales personalizada como solución alternativa para pasar tokens NotebookUtils a los clientes de Azure SDK.

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

Sugerencia

Los tokens expiran después de un período de tiempo. Si su equipo portátil realiza operaciones prolongadas, debería implementar la lógica de actualización para solicitar un nuevo token antes de que expire el actual.

Consideraciones

  • Los ámbitos de token con pbi como audiencia pueden cambiar con el tiempo.

  • Cuando llamas a notebookutils.credentials.getToken("pbi"), el token devuelto tiene un ámbito limitado si el notebook se ejecuta bajo una entidad de servicio. El token no tiene el ámbito completo del servicio Fabric. Si el notebook se ejecuta bajo la identidad del usuario, el token retiene el ámbito completo del servicio Fabric, pero esto podría cambiar con mejoras de seguridad. Para asegurarse de que el token tiene el ámbito completo del servicio Fabric, use la autenticación MSAL en lugar de la notebookutils.credentials.getToken API. Para obtener más información, consulte Autenticación con el identificador de Entra de Microsoft.

  • Los ámbitos siguientes están disponibles cuando se llama a notebookutils.credentials.getToken con la clave de audiencia pbi en la identidad de la entidad de servicio:

    • Lakehouse.ReadWrite.All – Acceso de lectura y escritura a los elementos de Lakehouse
    • MLExperiment.ReadWrite.All – Acceso de lectura y escritura a los elementos del experimento de Machine Learning
    • MLModel.ReadWrite.All : acceso de lectura y escritura a los elementos del modelo de Machine Learning
    • Notebook.ReadWrite.All – Acceso de lectura y escritura a los elementos de Bloc de notas
    • SparkJobDefinition.ReadWrite.All – Acceso de lectura y escritura a los elementos de definición de trabajo de Spark
    • Workspace.ReadWrite.All : acceso de lectura y escritura a elementos del área de trabajo
    • Dataset.ReadWrite.All : acceso de lectura y escritura a los elementos del conjunto de datos

Sugerencia

Si necesita acceder a servicios adicionales de Fabric o a permisos más amplios con una entidad de servicio, use MSAL para Python para autenticarse directamente con el ámbito completo del servicio Fabric en lugar de confiar en getToken("pbi").

Obtener clave secreta

getSecret devuelve un secreto de Azure Key Vault para un punto de conexión y un nombre secreto de Azure Key Vault determinado. La llamada usa las credenciales de usuario actuales para autenticarse en Key Vault.

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

Puede recuperar varios secretos para crear cadenas de conexión o configurar servicios:

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

Nota:

Las salidas del cuaderno redactan automáticamente los valores secretos por motivos de seguridad. Si imprime o muestra un secreto recuperado, la salida muestra un marcador de posición redactado en lugar del valor real.

Use la URL completamente calificada de Key Vault con el formato https://<vault-name>.vault.azure.net/. Debe tener los permisos adecuados para acceder a Key Vault y a los secretos individuales.

Prácticas recomendadas de seguridad

Siga estas recomendaciones al trabajar con credenciales en cuadernos de Fabric:

  • Almacene todos los valores confidenciales en Azure Key Vault. Nunca inserte credenciales, cadenas de conexión o claves de API directamente en el código del cuaderno.
  • No registre valores secretos. Confíe en la eliminación automática de secretos en los outputs del notebook. Evite escribir secretos en archivos o pasarlos como parámetros de cuaderno.
  • Use la clave de audiencia correcta. Asigna la clave de audiencia al recurso de Azure de destino de modo que el token solo tenga los permisos que necesita.
  • Comprenda el contexto de identidad. Sepa si el cuaderno se ejecuta en la identidad del usuario o en una entidad de servicio, ya que los ámbitos de token disponibles pueden diferir. Pruebe la autenticación en contextos interactivos y de canalización.
  • Controlar la expiración del token. Los tokens expiran. En el caso de las operaciones de larga duración, implemente la lógica de actualización para solicitar un nuevo token antes de que expire el actual.
  • Limite el acceso a Key Vault. Conceda solo los permisos mínimos necesarios a Key Vault. Audite el acceso a secretos a través de los registros de diagnóstico de Azure Key Vault.
  • Use identidades administradas siempre que sea posible. Las identidades administradas reducen la necesidad de administrar las credenciales manualmente y proporcionan un flujo de autenticación más seguro.

Guardar secreto

putSecret almacena un secreto en el almacén de claves de Azure especificado. Si el secreto ya existe, el valor se actualiza.

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

Debe tener los permisos adecuados (Establecer permiso) en Azure Key Vault para escribir secretos.

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

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

Validación de token

Use isValidToken para comprobar si un token es válido y no ha expirado antes de llamar a una API con él.

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

Contenido relacionado

  • Last updated on