Compartilhar via

Utilitários de Credenciais do NotebookUtils para Fabric

Você pode usar os utilitários de credenciais para obter tokens de acesso e gerenciar segredos no Azure Key Vault. O notebookutils.credentials módulo se integra à ID do Microsoft Entra para aquisição de token e ao Azure Key Vault para gerenciamento de segredo, para que você possa se conectar aos recursos do Azure com segurança sem expor credenciais no código.

Os utilitários de credenciais estão disponíveis nos notebooks Python, PySpark, Scala e R. Os exemplos nesta página usam Python como o idioma principal, com equivalentes Scala e R mostrados em que a API pública dá suporte a eles.

Importante

Nunca codifique segredos ou credenciais diretamente no código do notebook. Sempre use o Azure Key Vault para armazenar valores confidenciais e recuperá-los em runtime com notebookutils.credentials.getSecret.

Restrições e segurança

Antes de usar utilitários de credenciais, lembre-se dessas restrições:

  • Expiração do token – os tokens expiram após um período. Para operações de execução prolongada, implemente a lógica de atualização para solicitar um novo token antes da expiração.
  • Limitações de escopo do principal de serviço – ao executar sob um principal de serviço, os tokens para o pbi destinatário têm escopos restritos em comparação com a identidade do usuário.
  • MSAL para escopo completo – Se você precisar do escopo de serviço completo do Fabric em um principal de serviço, use a autenticação MSAL em vez de getToken.
  • Redação secreta – o Notebook redige automaticamente valores secretos para evitar a exposição acidental.
  • Permissões do Key Vault – Você deve ter permissões apropriadas (Obter para leitura, Definir para gravação) no Azure Key Vault para acessar ou armazenar segredos.
  • Alterações de audiência – os escopos de audiência dos tokens 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 a seguir lista os métodos de credenciais disponíveis:

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

Obter o token

getToken retorna um token do Microsoft Entra para um determinado público-alvo. A tabela a seguir mostra as chaves de público disponíveis no momento:

Chave de audiência Recurso Caso de uso
storage Armazenamento do Azure Acessar o ADLS Gen2 e o Blob Storage
pbi Power BI Chamar APIs REST do Power BI e do Fabric
keyvault Azure Key Vault Recuperar segredos do Key Vault
kusto BD KQL do Synapse RTA Conectar o Azure Data Explorer

Execute o seguinte comando para obter o token:

notebookutils.credentials.getToken('audience Key')

Exemplos de uso de tokens

Você pode usar o token retornado para se autenticar em vários serviços do Azure.

Armazenamento do Azure

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

APIs REST do Power BI e do 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')

Usar tokens com o SDK do Azure

Blocos de anotações de malha não dão suporte DefaultAzureCredential diretamente. Você pode usar uma classe de credencial personalizada como uma solução alternativa para passar tokens NotebookUtils para clientes do SDK do 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}")

Dica

Os tokens expiram após um período de tempo. Se o laptop executar operações longas, implemente a lógica de atualização para obter um novo token antes que o atual expire.

Considerações

  • Escopos de token com pbi como audiência podem mudar ao longo do tempo.

  • Quando você chama notebookutils.credentials.getToken("pbi"), o token retornado tem escopo limitado se o notebook for executado em uma entidade de serviço. O token não tem o escopo de serviço completo do Fabric. Se o notebook for executado sob a identidade do usuário, o token ainda terá o escopo completo do serviço fabric, mas isso poderá mudar com melhorias de segurança. Para garantir que o token tenha o escopo de serviço completo do Fabric, use a autenticação MSAL em vez da notebookutils.credentials.getToken API. Para obter mais informações, consulte Authenticate with Microsoft Entra ID.

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

    • Lakehouse.ReadWrite.All – Acesso de leitura e gravação aos itens do Lakehouse
    • MLExperiment.ReadWrite.All – Acesso de leitura e gravação aos itens do Experimento do Machine Learning
    • MLModel.ReadWrite.All – Acesso de leitura e gravação a itens do Modelo do Machine Learning
    • Notebook.ReadWrite.All – Acesso de leitura e gravação a itens do Notebook
    • SparkJobDefinition.ReadWrite.All – Acesso de leitura e gravação aos itens de Definição de Trabalho do Spark
    • Workspace.ReadWrite.All – Acesso de leitura e gravação a itens do Workspace
    • Dataset.ReadWrite.All – Acesso de leitura e gravação a itens do conjunto de dados

Dica

Se você precisar de acesso a serviços adicionais do Fabric ou permissões mais amplas sob um principal do serviço, use MSAL para Python para autenticar diretamente com o escopo completo do serviço do Fabric em vez de depender de getToken("pbi").

Obter segredo

getSecret retorna um segredo do Azure Key Vault para um determinado ponto de extremidade do Azure Key Vault e um nome secreto. A chamada usa suas credenciais de usuário atuais para se autenticar no Key Vault.

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

Você pode recuperar vários segredos para criar cadeias de conexã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 você imprimir ou exibir um segredo recuperado, a saída mostrará um espaço reservado oculto em vez do valor real.

Use a URL totalmente qualificada do Key Vault no formato https://<vault-name>.vault.azure.net/. Você deve ter permissões apropriadas para acessar o Key Vault e os segredos individuais.

Melhores práticas de segurança

Siga estas recomendações ao trabalhar com credenciais em blocos de anotações do Fabric:

  • Armazene todos os valores confidenciais no Azure Key Vault. Nunca insira credenciais, cadeias de conexão ou chaves de API diretamente no código do notebook.
  • Não registre valores secretos. Conte com a redação automática de informações confidenciais nas saídas do notebook. Evite escrever segredos em arquivos ou passá-los como parâmetros de notebook.
  • Use a chave de público correta. Corresponda a chave de audiência ao recurso do Azure de destino para que o token tenha apenas as permissões necessárias.
  • Entenda o contexto de identidade. Saiba se o notebook é executado sob a identidade de usuário ou um principal de serviço, pois os escopos de token disponíveis podem diferir. Testar a autenticação em contextos interativos e de pipeline.
  • Gerenciar a expiração do token. Os tokens expiram. Para operações de execução prolongada, implemente a lógica de atualização para solicitar um novo token antes que o atual expire.
  • Limitar o acesso ao Key Vault. Conceda apenas as permissões mínimas necessárias ao Key Vault. Audite o acesso secreto por meio dos logs de diagnóstico do Azure Key Vault.
  • Use identidades gerenciadas quando possível. As identidades gerenciadas reduzem a necessidade de gerenciar credenciais manualmente e fornecem um fluxo de autenticação mais seguro.

Inserir segredo

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

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

Você deve ter permissões apropriadas (definir permissão) no Azure Key Vault para gravar 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