Partilhar via

Utilitários de NotebookUtils para credenciais no Fabric

Podes usar as utilidades de credenciais para obter tokens de acesso e gerir segredos no Azure Key Vault. O notebookutils.credentials módulo integra-se com o Microsoft Entra ID para aquisição de tokens e o Azure Key Vault para gestão de segredos, permitindo que se ligue aos recursos Azure de forma segura sem expor credenciais em código.

As utilidades de credenciais estão disponíveis em cadernos Python, PySpark, Scala e R. Os exemplos nesta página usam Python como linguagem principal, com equivalentes em Scala e R mostrados onde a API pública os suporta.

Importante

Nunca codifique segredos ou credenciais diretamente em código de caderno. Use sempre o Azure Key Vault para armazenar valores sensíveis e recuperá-los em tempo de execução com notebookutils.credentials.getSecret.

Restrições e segurança

Antes de usar utilidades de credenciais, esteja ciente destas restrições:

  • Expiração do token – Os tokens expiram após um período. Para operações de longa duração, implemente lógica de atualização para solicitar um novo token antes da expiração.
  • Limitações do âmbito da entidade de serviço – Quando se opera sob uma entidade de serviço, os tokens para o pbi destinatário têm permissões restritas em comparação com a identidade do utilizador.
  • MSAL para âmbito completo – Se precisar de ter o âmbito completo do serviço Fabric sob um service principal, utilize a autenticação MSAL em vez de getToken.
  • Redação de segredos – As saídas do bloco de notas ocultam automaticamente os valores secretos para prevenir exposição acidental.
  • Permissões Key Vault – Deve ter permissões apropriadas (Obter para leitura, Definir para escrita) no Azure Key Vault para aceder ou armazenar segredos.
  • Alterações de audiência – Os escopos de audiência token podem evoluir ao longo do tempo. Verifique os escopos atuais na documentação.

Execute o seguinte comando para obter uma visão geral dos métodos disponíveis:

notebookutils.credentials.help()

A tabela seguinte lista os métodos de credenciais disponíveis:

Método Signature Descrição
getToken getToken(audience: String): String Devolve um token Microsoft Entra para o público especificado.
getSecret getSecret(akvName: String, secret: String): String Devolve o valor de um segredo do Azure Key Vault especificado.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Armazena um segredo no Azure Key Vault especificado. Este método não está disponível na API pública do Scala.
isValidToken isValidToken(token: String): Boolean Verifica se o token dado é válido e não expirado. Este método não está disponível na API pública do Scala.

Obter token

getToken devolve um token da Microsoft Entra para uma dada audiência. A tabela seguinte mostra as chaves de audiência atualmente disponíveis:

Chave do público Recurso Caso de utilização
storage Armazenamento do Azure Aceder ao ADLS Gen2 e Armazenamento Blob
pbi Power BI Chamar APIs REST do Power BI e Fabric
keyvault Azure Key Vault Recuperar segredos do Cofre da Chave
kusto Synapse RTA KQL DB Ligar ao Azure Data Explorer

Execute o seguinte comando para obter o token:

notebookutils.credentials.getToken('audience Key')

Exemplos de utilização de tokens

Pode usar o token devolvido para autenticar contra vários serviços Azure.

Armazenamento do Azure

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

APIs do Power BI e do Fabric REST

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

Use tokens com os SDK da Azure

Os cadernos Fabric não suportam DefaultAzureCredential diretamente. Pode usar uma classe de credencial personalizada como solução alternativa para passar tokens NotebookUtils aos clientes do 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}")

Sugestão

Os tokens expiram após um período de tempo. Se o seu portátil realizar operações prolongadas, implemente uma lógica de renovação para solicitar um novo token antes que o atual expire.

Considerações

  • Os escopos dos tokens com pbi como audiência podem mudar ao longo do tempo.

  • Quando chama notebookutils.credentials.getToken("pbi"), o token devolvido tem um alcance limitado se o notebook estiver a ser executado sob um principal de serviço. O token não tem o âmbito completo do serviço Fabric. Se o portátil correr sob a identidade do utilizador, o token ainda tem todo o âmbito do serviço Fabric, mas isso pode mudar com melhorias de segurança. Para garantir que o token tem o âmbito completo do serviço Fabric, use a autenticação MSAL em vez da API notebookutils.credentials.getToken. Para obter mais informações, consulte Autenticar com o Microsoft Entra ID.

  • Os seguintes escopos estão disponíveis quando chama notebookutils.credentials.getToken com a chave de audiência pbi sob a identidade do principal de serviço:

    • Lakehouse.ReadWrite.All – Acesso de leitura e escrita aos itens do Lakehouse
    • MLExperiment.ReadWrite.All – Acesso de leitura e escrita aos itens do Experimento de Aprendizagem Automática
    • MLModel.ReadWrite.All – Acesso de leitura e escrita aos itens do Modelo de Aprendizagem Automática
    • Notebook.ReadWrite.All – Acesso de leitura e escrita aos itens do Caderno
    • SparkJobDefinition.ReadWrite.All – Acesso de leitura e escrita aos elementos de Definição de Tarefas Spark
    • Workspace.ReadWrite.All – Acesso de leitura e escrita aos itens do Workspace
    • Dataset.ReadWrite.All – Acesso de leitura e escrita aos itens do conjunto de dados

Sugestão

Se precisar de acesso a serviços Fabric adicionais ou permissões mais amplas sob um princípio de serviço, use MSAL para Python para autenticar diretamente com todo o âmbito do serviço Fabric em vez de depender de getToken("pbi").

Obtenha segredo

getSecret retorna um segredo do Azure Key Vault para um dado ponto final do Azure Key Vault e nome do segredo. A chamada utiliza as suas credenciais de utilizador atuais para se autenticar contra o Key Vault.

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

Pode recuperar múltiplos segredos para construir strings de ligação ou configurar serviços:

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

Observação

As saídas do notebook ocultam automaticamente valores secretos para segurança. Se imprimir ou mostrar um segredo recuperado, o resultado mostra um marcador de posição censurado em vez do valor real.

Use a URL totalmente qualificada do Key Vault no formato https://<vault-name>.vault.azure.net/. Deve ter as permissões adequadas para aceder ao Cofre da Chave e aos segredos individuais.

Práticas recomendadas de segurança

Siga estas recomendações quando trabalhar com credenciais em cadernos Fabric:

  • Armazene todos os valores sensíveis no Azure Key Vault. Nunca incorpores credenciais, strings de ligação ou chaves API diretamente no código do notebook.
  • Não guarde valores secretos. Confie na redação automática de dados sensíveis nas saídas dos notebooks. Evita escrever segredos em ficheiros ou passá-los como parâmetros de caderno.
  • Use a chave de audiência correta. Associe a chave de audiência ao recurso Azure alvo para que o token tenha apenas as permissões necessárias.
  • Compreenda o contexto da identidade. Saiba se o seu portátil corre sob identidade de utilizador ou com um principal de serviço, pois os escopos de tokens disponíveis podem ser diferentes. Teste a autenticação tanto em contextos interativos como em pipeline.
  • Gerencie a expiração do token. Os tokens expiram. Para operações de longa duração, implemente lógica de atualização para solicitar um novo token antes de expirar o atual.
  • Limitar o acesso ao Cofre de Chaves. Conceda apenas as permissões mínimas necessárias ao seu Cofre de Chaves. Auditar o acesso secreto através dos registos de diagnóstico do Azure Key Vault.
  • Use identidades geridas sempre que possível. As identidades geridas reduzem a necessidade de gerir as credenciais manualmente e proporcionam um fluxo de autenticação mais seguro.

Guardar segredo

putSecret armazena um segredo no Azure Key Vault especificado. Se o segredo já existir, o valor é atualizado.

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

Deve ter as permissões apropriadas (Permissão de Definição) no Azure Key Vault para escrever segredos.

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

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

Validar token

Use isValidToken para verificar se um token é válido e não expirou antes de chamar uma API com ele.

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

Conteúdo relacionado

  • Last updated on