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.

Podes usar os utilitários de credenciais nos notebooks Python e Fabric Spark. Nos notebooks Fabric Spark, pode usar PySpark, Scala ou R. A disponibilidade dos métodos varia consoante o tempo de execução e a API do notebook. Por exemplo, putSecret só funciona em blocos de notas Python, que utilizam o ambiente de execução do Python. Os notebooks Spark não suportam isso, mesmo quando executam código Python com PySpark. Os notebooks Spark que usam Scala ou R também não suportam isso.

Os exemplos seguintes usam Python como linguagem principal. Os equivalentes Scala e R aparecem onde o tempo de execução do notebook e a API pública suportam o método.

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.
  • Ocultação de segredos – A saída do notebook tenta ocultar o valor original do segredo quando o código o imprime ou o apresenta diretamente. Esta salvaguarda, na medida do possível, reduz a divulgação inadvertida, inclusive durante a partilha de ecrã. Não é uma fronteira de segurança. Após a recuperação, o código autorizado do caderno recebe texto simples e pode processar, transformar ou divulgar o conteúdo secreto ou derivado do segredo.
  • 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 funciona apenas em cadernos que utilizam o runtime em Python. Os notebooks Spark não suportam isso, mesmo quando executam código Python com PySpark. Os notebooks Spark que usam Scala ou R também não suportam isso.
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 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}")

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 da casa do lago
    • MLExperiment.ReadWrite.All – Acesso de leitura e escrita a itens experimentais
    • MLModel.ReadWrite.All – Acesso de leitura e escrita aos itens do modelo de ML
    • Notebook.ReadWrite.All – Acesso de leitura e escrita aos itens do caderno
    • SparkJobDefinition.ReadWrite.All – Acesso de leitura e escrita aos itens de definição de funções do Spark
    • Workspace.ReadWrite.All – Acesso de leitura e escrita aos espaços de trabalho
    • Dataset.ReadWrite.All – Acesso de leitura e escrita a itens semânticos do modelo

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

Importante

Após a recuperação bem-sucedida, o código autorizado do caderno recebe o valor secreto como texto simples. O resultado do notebook tenta ocultar o valor secreto original quando o código o imprime ou mostra diretamente.

Esta medida de proteção de melhor esforço reduz a divulgação inadvertida na saída do bloco de notas, incluindo durante a partilha de ecrã. Não é uma fronteira de segurança e não impede o processamento, transformação ou divulgação de conteúdos derivados de segredos.

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 reveles valores secretos. Não imprimas nem registes segredos, não os graves em ficheiros nem os passes como parâmetros do notebook. A redação de saída tenta proteger o valor original na saída direta do caderno. Não impede a divulgação de conteúdos derivados de segredos.
  • 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

putSecretarmazena ou atualiza um segredo no Azure Key Vault especificado. Funciona apenas em cadernos que usam o runtime em Python.

Importante

Os cadernos Spark não suportamputSecret, mesmo quando executam código Python com PySpark. Os notebooks Spark que usam Scala ou R também não suportam isso. Usa um caderno Python, que utiliza o runtime Python.

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

Para escrever segredos, precisas de permissões apropriadas (Definir permissão) no Azure Key Vault. Execute o seguinte exemplo apenas num caderno que utilize o runtime em Python. Não o uses num bloco de notas do 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")

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

  • Última atualização a