Obtenha tokens de ID do Microsoft Entra manualmente

Esta página descreve como gerar manualmente tokens de acesso da ID do Microsoft Entra para usuários e entidades de serviço se autenticarem com APIs REST do Azure Databricks. A geração de token manual é uma técnica avançada.

Quando usar a geração manual de token

Use a geração manual de token somente quando:

• Você precisa se integrar a sistemas que não podem usar a CLI do Azure ou a autenticação unificada
• Você precisa de controle explícito sobre o ciclo de vida do token e a atualização
• Você está debugando problemas de autenticação

Para todos os outros casos de uso, use os métodos de autenticação recomendados que lidam com o gerenciamento de tokens automaticamente.

Obter tokens para usuários

Use a CLI do Azure ou a MSAL (Biblioteca de Autenticação da Microsoft) para obter tokens de acesso da ID do Microsoft Entra para usuários.

Método da CLI do Azure

1. Obtenha a ID da assinatura do Azure para sua conta de usuário:

   • No workspace do Azure Databricks: Clique no seu nome de usuário >Visão geral no Portal do > e localize a ID da Assinatura.

   • Com a CLI do Azure: Execute o seguinte comando (substitua pela URL do workspace):

     az databricks workspace list --query "[?workspaceUrl==\`adb-0000000000000000.0.azuredatabricks.net\`].{id:id}" -o tsv
     
     # /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-rg/providers/Microsoft.Databricks/workspaces/my-ws
     

     O 00000000-0000-0000-0000-000000000000 seguinte /subscriptions/ é a ID da assinatura.

     Se você receber um erro de locatário, entre no locatário correto:

     az login -t <tenant-id>
     

     Consulte Obter IDs de assinatura e locatário no portal do Azure.

2. Entrar no Azure:

   az login
   

3. Defina a assinatura correta:

   az account set -s <subscription-id>
   

4. Gere o token de acesso:

   az account get-access-token \
   --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d \
   --query "accessToken" \
   -o tsv
   

   A ID 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d do recurso é o identificador padrão do Azure Databricks em todos os ambientes do Azure.

Método MSAL

Use a Biblioteca de Autenticação da Microsoft (MSAL) para obter programaticamente tokens de acesso do Microsoft Entra IDs. A MSAL dá suporte a dois fluxos:

• Fluxo de código de autorização (interativo): Inicia um navegador para entrada do usuário. Use isso quando a autenticação federada ou de dois fatores estiver habilitada ou quando o consentimento do administrador for necessário.
• Fluxo de senha de nome de usuário (programático): Autentica com um nome de usuário e senha. Use isso somente quando você tiver autorização para autenticar-se programaticamente.

Antes de usar a MSAL, você deve registrar um aplicativo na ID do Microsoft Entra. Consulte Registrar um aplicativo usando o portal do Azure. Ao registrar:

1. Defina Tipos de conta suportados para Contas somente neste diretório organizacional (locatário único).
2. Defina o URI de Redirecionamento como cliente público/nativo (móvel &desktop) com valor http://localhost.
3. Anote o ID do Aplicativo (cliente) e o ID do Diretório (locatário) na página de Visão Geral do aplicativo.
4. Adicione a permissão da API do AzureDatabricks :
   1. Vá para permissões> de APIAdicionar uma permissão.
   2. Pesquise e selecione AzureDatabricks.
   3. Habilite user_impersonation e clique em Adicionar permissões.
   4. Clique em Conceder consentimento do administrador (requer privilégios de administrador).

Fluxo do código de autorização

Instale o SDK do Python da MSAL:

pip install msal

Salve o seguinte código como get-tokens.py:

from msal import PublicClientApplication
import sys

# Provide client ID and tenant ID as command-line arguments
client_id = sys.argv[1] if len(sys.argv) > 1 else '<client-id>'
tenant_id = sys.argv[2] if len(sys.argv) > 1 else '<tenant-id>'

scopes = ['2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default']

app = PublicClientApplication(
  client_id=client_id,
  authority=f"https://login.microsoftonline.com/{tenant_id}"
)

result = app.acquire_token_interactive(scopes=scopes)

if 'error' in result:
  print(f"Error: {result['error']}")
  print(f"Description: {result['error_description']}")
else:
  print(f"Access token:\n{result['access_token']}")
  print(f"\nRefresh token:\n{result['refresh_token']}")

Execute o script:

python get-tokens.py <client-id> <tenant-id>

Fluxo de nome de usuário-senha

Salve o seguinte código como get-tokens-user.py:

from msal import PublicClientApplication
import sys

client_id = sys.argv[1] if len(sys.argv) > 1 else '<client-id>'
tenant_id = sys.argv[2] if len(sys.argv) > 1 else '<tenant-id>'
username = sys.argv[3] if len(sys.argv) > 1 else '<username>'
password = sys.argv[4] if len(sys.argv) > 1 else '<password>'

scopes = ['2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default']

app = PublicClientApplication(
  client_id=client_id,
  authority=f"https://login.microsoftonline.com/{tenant_id}"
)

result = app.acquire_token_by_username_password(
  username=username,
  password=password,
  scopes=scopes
)

if 'error' in result:
  print(f"Error: {result['error']}")
  print(f"Description: {result['error_description']}")
else:
  print(f"Access token:\n{result['access_token']}")
  print(f"\nRefresh token:\n{result['refresh_token']}")

Execute o script:

python get-tokens-user.py <client-id> <tenant-id> <username> <password>

Obter tokens para entidades de serviço

As entidades de serviço usam o fluxo de credenciais do cliente OAuth 2.0 e podem ter um controle de acesso diferente dos usuários comuns.

Criar um principal de serviço

Se você não tiver uma entidade de serviço, crie uma usando o portal do Azure ou a CLI do Azure:

portal do Azure

1. Entre no portal do Azure.
2. Alterne para o inquilino correto usando Diretórios + assinaturas se necessário.
3. Pesquise e selecione Microsoft Entra ID.
4. Clique em + Adicionar>registro de aplicativo.
5. Insira um Nome e selecione Somente contas neste diretório organizacional (locatário único).
6. Clique em Registrar.
7. Copie esses valores da página Visão geral :
   • ID do aplicativo (cliente)
   • ID do Diretório (locatário)
8. Vá para Certificados & segredosSegredos do ClienteNovo segredo do cliente.
9. Adicione uma descrição, defina um período de expiração e clique em Adicionar.
10. Copie e armazene com segurança o valor do segredo do cliente.

CLI do Azure

Consulte Criar um principal de serviço do Azure com a CLI do Azure para obter instruções completas.

Gerar um token

Gere um token usando a API REST ou a CLI do Azure. Reúna as seguintes informações primeiro:

• ID do locatário: O ID do Diretório (locatário) do Microsoft Entra ID
• ID do cliente:ID do aplicativo (cliente) do Microsoft Entra ID
• Segredo do cliente: O valor do segredo do cliente do Microsoft Entra ID

Método da API REST

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \
-d 'client_id=<client-id>' \
-d 'grant_type=client_credentials' \
-d 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default' \
-d 'client_secret=<client-secret>'

O token de acesso está no access_token campo da resposta.

Método da CLI do Azure

1. Obtenha sua ID de assinatura do Azure. Consulte Obter tokens para usuários.

2. Faça login com seu principal de serviço:

   az login \
   --service-principal \
   -t <tenant-id> \
   -u <client-id> \
   -p <client-secret>
   

3. Defina a assinatura correta:

   az account set -s <subscription-id>
   

4. Gere o token de acesso:

   az account get-access-token \
   --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d \
   --query "accessToken" \
   -o tsv
   

Usar tokens com APIs do Databricks

Depois de gerar um token, use-o com a API REST do Databricks.

Principais de serviço no workspace

Se sua entidade de serviço já estiver adicionada ao workspace usando a API de Entidades de Serviço ou a CLI do Databricks:

CLI do Databricks

databricks clusters list -p <profile-name-with-token>

encurvar

curl -X GET \
-H 'Authorization: Bearer <access-token>' \
https://<databricks-instance>/api/2.0/clusters/list

Principais de serviço com papel no Azure

Se a entidade de serviço tiver a função Contributor ou Owner no recurso de workspace no Azure, mas ainda não estiver no workspace do Azure Databricks:

1. Obtenha um token de gerenciamento para o Azure Resource Manager:

   curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
   https://login.microsoftonline.com/<tenant-id>/oauth2/token \
   -d 'client_id=<client-id>' \
   -d 'grant_type=client_credentials' \
   -d 'resource=https%3A%2F%2Fmanagement.core.windows.net%2F' \
   -d 'client_secret=<client-secret>'
   

2. Chame a API do Databricks com ambos os tokens:

   curl -X GET \
   -H 'Authorization: Bearer <databricks-access-token>' \
   -H 'X-Databricks-Azure-SP-Management-Token: <management-access-token>' \
   -H 'X-Databricks-Azure-Workspace-Resource-Id: /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Databricks/workspaces/<workspace-name>' \
   https://<databricks-instance>/api/2.0/clusters/list
   

Após a primeira autenticação, o principal de serviço se torna um administrador do espaço de trabalho.

Tokens de atualização

Se você obteve um token de atualização com o token de acesso, use-o para obter um novo token. Os tokens de acesso da ID do Microsoft Entra expiram após 60 a 90 minutos por padrão.

Salve o seguinte código como refresh-tokens.py:

from msal import PublicClientApplication
import sys

client_id = sys.argv[1] if len(sys.argv) > 1 else '<client-id>'
tenant_id = sys.argv[2] if len(sys.argv) > 1 else '<tenant-id>'
refresh_token = sys.argv[3] if len(sys.argv) > 1 else '<refresh-token>'

scopes = ['2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default']

app = PublicClientApplication(
  client_id=client_id,
  authority=f"https://login.microsoftonline.com/{tenant_id}"
)

result = app.acquire_token_by_refresh_token(
  refresh_token=refresh_token,
  scopes=scopes
)

if 'error' in result:
  print(f"Error: {result['error']}")
  print(f"Description: {result['error_description']}")
else:
  print(f"\nNew access token:\n{result['access_token']}")
  print(f"\nNew refresh token:\n{result['refresh_token']}")

Execute o script:

python refresh-tokens.py <client-id> <tenant-id> <refresh-token>

Solucionar problemas de token

Esta seção descreve erros comuns de token e como validar tokens de acesso.

Falha ao obter o token com nome de usuário e senha

The user or administrator has not consented to use the application with ID <client-id>.
Send an interactive authorization request for this user and resource.

Solução: Verifique se o recurso do AzureDatabricks foi adicionado ao seu aplicativo. Use o fluxo de código de autorização (método interativo) para consentir com permissões. Depois de consentir, você pode usar o fluxo de nome de usuário e senha. Consulte Obter tokens para usuários.

Os URIs de redirecionamento não são correspondentes

The reply URL specified in the request does not match the reply URLs configured for the application: '<application-id>'

Solução: Verifique se o URI de redirecionamento em sua solicitação corresponde a um configurado no aplicativo.

Validar um token de acesso

Verifique se o token de acesso à ID do Microsoft Entra inclui as informações corretas. Consulte tokens de validação.

• aud: 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d (ID do recurso do Databricks)
• iss: https://sts.windows.net/<tenant-id>/
• tid: ID do locatário do workspace
• nbf/exp: o tempo atual fica entre esses valores
• unique_name: O utilizador existe no espaço de trabalho

Valide a assinatura usando os certificados públicos dos endpoints OIDC.

Decodificar sem verificação de assinatura:

O código a seguir mostra a carga útil do token. Primeiro, você deve instalar a biblioteca PyJWT usando pip install pyjwt e a biblioteca de criptografia usando pip install cryptography.

import jwt

def decode_token(token):
  algorithm = jwt.get_unverified_header(token)['alg']
  decoded = jwt.decode(token, algorithms=[algorithm], options={"verify_signature": False})
  for key in decoded.keys():
    print(f"{key}: {str(decoded[key])}")

Decodificar com a verificação de assinatura:

import jwt
import requests
from cryptography.x509 import load_pem_x509_certificate
from cryptography.hazmat.backends import default_backend

PEMSTART = '-----BEGIN CERTIFICATE-----\n'
PEMEND = '\n-----END CERTIFICATE-----\n'

def get_public_key_for_token(kid):
  response = requests.get('https://login.microsoftonline.com/common/.well-known/openid-configuration').json()
  pubkeys = requests.get(response['jwks_uri']).json()['keys']

  for key in pubkeys:
    if key['kid'] == kid:
      cert_str = PEMSTART + str(key['x5c'][0]) + PEMEND
      cert_obj = load_pem_x509_certificate(bytes(cert_str, 'ascii'), default_backend())
      return cert_obj.public_key()

def aad_access_token_decoder(access_token):
  header = jwt.get_unverified_header(access_token)
  public_key = get_public_key_for_token(header['kid'])
  decoded = jwt.decode(access_token, key=public_key, algorithms='RS256',
                      audience='2ff814a6-3304-4ab8-85cb-cd0e6f879c1d')
  for key in decoded.keys():
    print(f"{key}: {str(decoded[key])}")

Use decodificadores JWT online, como jwt.ms ou jwt.io para tokens não confidenciais.