Obter tokens de identificação do Microsoft Entra manualmente

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

Quando usar a geração manual de tokens

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

• Você precisa integrar com 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 e a atualização do token
• Você está depurando problemas de autenticação

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

Obter tokens para usuários

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

Método CLI do Azure

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

   • No espaço de trabalho do Azure Databricks: Clique no seu nome > de utilizadorVisão Geral do > do Azure e localize o ID da Subscrição.

   • Com a CLI do Azure: Execute o seguinte comando (substitua pelo URL do espaço de trabalho):

     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 após /subscriptions/ é o seu ID de subscrição.

     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. Entre 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 para o Azure Databricks em todos os ambientes do Azure.

Método MSAL

Utilize a Biblioteca de Autenticação da Microsoft (MSAL) para obter tokens de acesso do Microsoft Entra ID programaticamente. O MSAL suporta dois fluxos:

• Fluxo de código de autorização (interativo): Inicia um navegador para login 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 nome de usuário-senha (programático): Autentica com um nome de usuário e senha. Utilize isto apenas quando tiver permissão para iniciar sessão programaticamente.

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

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

Fluxo de código de autorização

Instale o SDK do MSAL Python:

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']}")

Executar 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']}")

Executar 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 controlo de acesso diferente dos utilizadores comuns.

Criar um "service principal"

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. Inicie sessão no portal Azure.
2. Mude para o inquilino correto através de Diretórios + subscrições, caso seja necessário.
3. Procure e selecione Microsoft Entra ID.
4. Clique em + Adicionar>registro de aplicativo.
5. Insira um Nome e selecione Contas somente neste diretório organizacional (Tenant único).
6. Clique em Registar.
7. Copie estes valores da página Visão geral :
   • ID do aplicativo (cliente)
   • ID da diretoria (tenant)
8. Vá para Certificados & segredos>Segredos do cliente>Novo 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 secreto do cliente.

Azure CLI (Interface de Linha de Comando da Azure)

Consulte Criar uma entidade 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 primeiro as seguintes informações:

• ID do locatário: O identificador de locatário do Microsoft Entra ID
• ID do cliente: A ID do aplicativo (cliente) da ID do Microsoft Entra
• Segredo do cliente: O valor secreto do cliente da ID do Microsoft Entra

Método REST API

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 CLI do Azure

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

2. Inicie sessão com a entidade 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 espaço de trabalho

Se a entidade de serviço já tiver sido adicionada ao espaço de trabalho usando a API de Entidades de Serviço ou a CLI do Databricks:

CLI do Databricks

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

encaracolar

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

Entidades de serviço com função do Azure

Se a entidade de serviço possui a função ou no recurso do espaço de trabalho no Azure, mas ainda não está incluída no espaço de trabalho 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 os dois 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 torna-se um administrador do espaço de trabalho.

Atualizar tokens

Se você obteve um token de atualização com seu token de acesso, use-o para obter um novo token. Os tokens de acesso do Microsoft Entra ID expiram após 60-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']}")

Executar o script:

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

Solucionar problemas de token

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

Falha ao obter 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 AzureDatabricks foi adicionado ao seu aplicativo. Use o fluxo de código de autorização (método interativo) para consentir com permissões. Após consentir, pode-se utilizar o fluxo de autenticação com nome de utilizador e senha. Consulte Obter tokens para usuários.

Os URIs de redirecionamento não correspondem

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

Certifique-se de que o token de acesso do Microsoft Entra ID inclui as informações corretas. Consulte a secção validar tokens.

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

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

Descodificar sem verificação de assinatura:

O código a seguir mostra a carga útil do token. Você deve primeiro 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])}")

Descodificar com 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 on-line como jwt.ms ou jwt.io para tokens não confidenciais.