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.

Puedes usar las utilidades de credenciales en los cuadernos Python y Fabric Spark. En los cuadernos Fabric Spark, puedes usar PySpark, Scala o R. La disponibilidad de métodos varía según el tiempo de ejecución y la API del cuaderno. Por ejemplo, putSecret solo funciona en cuadernos Python, que usan el runtime de Python. Los cuadernos de Spark no lo soportan, ni siquiera cuando ejecutan código en Python con PySpark. Los cuadernos Spark que usan Scala o R tampoco lo soportan.

Los siguientes ejemplos utilizan Python como lenguaje principal. Los equivalentes en Scala y R se muestran cuando el entorno de ejecución del cuaderno y la API pública admiten este método.

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 – La salida del cuaderno intenta tachar el valor secreto original cuando el código lo imprime o muestra directamente. Esta medida de protección, de eficacia limitada, reduce la revelación accidental, incluso al compartir pantalla. No es una barrera de seguridad. Tras la recuperación, el código autorizado del cuaderno recibe texto plano y puede procesar, transformar o revelar el contenido secreto o derivado de secretos.
  • 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 solo funciona en cuadernos que usan el entorno de ejecución de Python. Los cuadernos de Spark no lo soportan, ni siquiera cuando ejecutan código en Python con PySpark. Los notebooks Spark que usan Scala o R tampoco lo soportan.
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 SDK de 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}")

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 elementos de lakehouse
    • MLExperiment.ReadWrite.All – Acceso de lectura y escritura a los elementos experimentales
    • MLModel.ReadWrite.All – Acceso de lectura y escritura a los elementos del modelo de ML
    • Notebook.ReadWrite.All – Acceso a lectura y escritura de elementos del cuaderno
    • SparkJobDefinition.ReadWrite.All – Acceso de lectura y escritura a los elementos de definición de trabajos de Spark
    • Workspace.ReadWrite.All – Acceso de lectura y escritura a los espacios de trabajo
    • Dataset.ReadWrite.All – Acceso para leer y escribir a los elementos semánticos del modelo

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

Importante

Tras la recuperación exitosa, el código autorizado del cuaderno recibe el valor secreto como texto plano. La salida del cuaderno intenta ocultar el valor secreto original cuando el código lo imprime o lo muestra directamente.

Esta medida de protección, aunque no es infalible, reduce la exposición accidental en la salida del cuaderno, incluso al compartir pantalla. No es una frontera de seguridad y no impide el procesamiento, transformación o divulgación de contenido derivado de secretos.

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 reveles valores secretos. No imprimas ni registres secretos, no los escribas en archivos ni los pases como parámetros del cuaderno. La redacción de salida intenta proteger el valor original en la salida directa del cuaderno. No impide la divulgación de contenido derivado de secretos.
  • 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

putSecretalmacena o actualiza un secreto en el Azure Key Vault especificado. Solo funciona en cuadernos que usan el entorno de ejecución de Python.

Importante

Los cuadernos de Spark no lo soportanputSecret, ni siquiera cuando ejecutan código en Python con PySpark. Los notebooks Spark que usan Scala o R tampoco lo soportan. Usa un cuaderno de Python, que utiliza el runtime de Python.

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

Para escribir secretos, necesitas los permisos apropiados (Establecer permisos) en Azure Key Vault. Ejecuta el siguiente ejemplo solo en un cuaderno que use el entorno de ejecución de Python. No lo ejecutes en un cuaderno de 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")

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