Obter tokens do Microsoft Entra ID (anteriormente Azure Ative Directory) para usuários usando o MSAL
Importante
Este artigo descreve como criar manualmente tokens do Microsoft Entra ID (anteriormente Azure Ative Directory) usando a Biblioteca de Autenticação da Microsoft (MSAL).
O Databricks não recomenda que você crie tokens do Microsoft Entra ID (anteriormente Azure Ative Directory) para usuários do Azure Databricks manualmente. Isso ocorre porque cada token de ID do Microsoft Entra é de curta duração, normalmente expirando dentro de uma hora. Após esse período, você deve gerar manualmente um token de ID do Microsoft Entra de substituição. Em vez disso, use uma das ferramentas participantes ou SDKs que implementam o padrão de autenticação unificada do cliente Databricks. Essas ferramentas e SDKs geram e substituem automaticamente tokens de ID do Microsoft Entra expirados para você, aproveitando a autenticação da CLI do Azure.
As entidades de serviço gerenciado do Azure Databricks são gerenciadas diretamente no Azure Databricks. As entidades de serviço gerenciadas do Microsoft Entra ID são gerenciadas no Microsoft Entra ID, o que requer permissões adicionais. O Databricks recomenda que você use entidades de serviço gerenciado do Azure Databricks para a maioria dos casos de uso. No entanto, o Databricks recomenda que você use entidades de serviço gerenciado do Microsoft Entra ID nos casos em que você deve se autenticar com o Azure Databricks e outros recursos do Azure ao mesmo tempo.
Para criar uma entidade de serviço gerenciado do Azure Databricks em vez de uma entidade de serviço gerenciado do Microsoft Entra ID, consulte Gerenciar entidades de serviço.
Você pode usar a Microsoft Authentication Library (MSAL) para adquirir tokens de acesso do Microsoft Entra ID programaticamente. Este artigo descreve o uso básico da biblioteca MSAL e as entradas de usuário necessárias, com exemplos de Python.
Nota
O MSAL substitui a Microsoft Entra ID Authentication Library (ADAL). Todo o suporte e desenvolvimento da Microsoft para a ADAL, incluindo correções de segurança, terminou em 30 de junho de 2022. Consulte Migrar aplicativos para a Microsoft Authentication Library (MSAL).
Gorjeta
Talvez você queira tentar usar a CLI do Azure em vez da MSAL para obter tokens de ID do Microsoft Entra para os usuários, já que usar a CLI do Azure envolve menos etapas. Consulte Obter tokens do Microsoft Entra ID (anteriormente Azure Ative Directory) para usuários usando a CLI do Azure.
Você também pode definir uma entidade de serviço no Microsoft Entra ID e obter um token de acesso do Microsoft Entra ID para a entidade de serviço em vez de para um usuário. Consulte Obter tokens do Microsoft Entra ID (anteriormente Azure Ative Directory) para entidades de serviço.
Configurar um aplicativo no portal do Azure
Registre um aplicativo com o ponto de extremidade Microsoft Entra ID no portal do Azure. Como alternativa, você pode usar um aplicativo Microsoft Entra ID que já esteja registrado. Para obter mais informações, consulte Registrar um aplicativo usando o portal do Azure.
Inicie sessão no portal do Azure.
Nota
O portal a ser usado é diferente dependendo se seu aplicativo Microsoft Entra ID é executado na nuvem pública do Azure ou em uma nuvem nacional ou soberana. Para obter mais informações, consulte Nuvens nacionais.
Se você tiver acesso a vários locatários, assinaturas ou diretórios, clique no ícone Diretórios + assinaturas (diretório com filtro) no menu superior para alternar para o diretório no qual deseja registrar o aplicativo.
Procure e selecione Microsoft Entra ID.
Em Gerir, selecione Registos de > aplicações Novo registo.
Em Nome, insira um nome para o aplicativo.
Na seção Tipos de conta suportados, selecione Contas somente neste diretório organizacional (Locatário único).
Na seção Redirecionar URI (opcional), para Selecionar uma plataforma, selecione Cliente público/nativo (móvel ou desktop) e insira um URI de redirecionamento. No exemplo a seguir, o valor de URI de redirecionamento é
http://localhost.
Clique em Registar.
Na página Visão geral da página do aplicativo, na seção Essenciais, copie os seguintes valores:
- ID do aplicativo (cliente)
- ID do diretório (locatário)
- Em Redirecionar URIs, o cliente público redireciona o URI inserido anteriormente neste procedimento.
Adicione AzureDatabricks às permissões necessárias do aplicativo registrado. Você deve ser um usuário administrador para executar esta etapa. Se você encontrar um problema relacionado a permissões enquanto executa essa ação, entre em contato com o administrador para obter ajuda.
Na página Visão geral da página do aplicativo, na guia Introdução, clique em Exibir permissões da API.
Clique em Adicionar uma permissão.
No painel Permissões de API de solicitação, clique na guia APIs que minha organização usa, procure AzureDatabricks e selecione-o.
Habilite a caixa de seleção user_impersonation e clique em Adicionar permissões.
Clique em Conceder consentimento de administrador para ### e, em seguida, em Sim. Para executar essa ação, você deve ser um usuário administrador ou ter o privilégio de conceder consentimento ao aplicativo. Se você não vir Conceder consentimento de administrador para ###, ou se ignorar esta ação, deverá usar o fluxo de código de autorização (interativo) na primeira vez que usar o aplicativo para fornecer consentimento. Depois disso, você pode usar o método de fluxo de nome de usuário-senha (programático).
Você pode adicionar outros usuários ao aplicativo. Para obter mais informações, consulte Atribuir uma conta de usuário a um aplicativo corporativo para obter instruções do portal do Azure ou Atribuir usuários e grupos a um aplicativo no Microsoft Entra ID (anteriormente Azure Ative Directory) para obter instruções do PowerShell. Um usuário não poderá obter um token sem as permissões necessárias.
Obter um token de acesso do Microsoft Entra ID
Para obter um token de acesso do Microsoft Entra ID, você pode usar:
Você deve usar o fluxo de código de autorização (interativo) para obter o token de acesso do Microsoft Entra ID se:
- A autenticação de dois fatores está habilitada no Microsoft Entra ID.
- A autenticação federada está habilitada no Microsoft Entra ID.
- Não lhe é concedido consentimento para o pedido registado durante o registo do pedido.
Se você tiver autoridade para entrar com um nome de usuário e senha, poderá usar o fluxo de nome de usuário-senha (programático) para obter um token de acesso do Microsoft Entra ID.
Fluxo de código de autorização (interativo)
Há duas etapas para adquirir um token de acesso do Microsoft Entra ID usando o fluxo de código de autorização.
- Solicite um código de autorização, que inicia uma janela do navegador e solicita o logon de usuário do Azure. O código de autorização é retornado depois que o usuário efetua login com êxito.
- Use o código de autorização para adquirir o token de acesso do Microsoft Entra ID. Dependendo da abordagem usada, um token de atualização também pode ser retornado ao mesmo tempo e pode ser usado para atualizar o token de acesso do Microsoft Entra ID.
Uma abordagem para concluir essas duas etapas é usar seu navegador da Web e enrolar. Para fazer isso, você usa seu navegador da Web para obter o código de autorização e, em seguida, você usa o código de autorização e curl para obter o token de acesso do Microsoft Entra ID. Essa abordagem não fornece um token de atualização.
Outra abordagem é usar a biblioteca MSAL Python. Para fazer isso, você executa um único script que usa seu navegador da Web para obter o código de autorização e, em seguida, usa o código de autorização para obter um token de acesso e atualização.
Ambas as abordagens pressupõem que você já esteja conectado ao Azure. Se você não estiver conectado, seu navegador da Web solicitará que você faça isso.
Obter tokens de ID do Microsoft Entra usando um navegador da Web e curl
Recolha as seguintes informações:
Parâmetro Description ID de Inquilino do A ID de diretório (locatário) para o aplicativo relacionado registrado na ID do Microsoft Entra em Configurar um aplicativo no portal do Azure. ID de Cliente A ID do aplicativo (cliente) para o aplicativo relacionado registrado no Microsoft Entra ID. Redirecionar URL Os URIs de redirecionamento apropriados para o aplicativo relacionado registrado no Microsoft Entra ID (por exemplo, http://localhost). As respostas de autenticação são enviadas para este URI com o código de autorização incluído.Obtenha o código de autorização usando seu navegador da Web para navegar até o seguinte URL. Substitua os campos no exemplo de URL a seguir de acordo. Observe que o URL deve ser enviado como uma única linha; quebras de linha foram adicionadas ao seguinte URL para facilitar a leitura. Para obter mais informações, consulte Solicitar um código de autorização.
https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-id> &response_type=code &redirect_uri=<redirect-uri> &response_mode=query &scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default &state=<state>Substituir:
<tenant-id>com o ID de locatário do aplicativo registrado.<client-id>com o ID de cliente da aplicação registada.<redirect-uri>com o URI de redirecionamento do aplicativo registrado. Esse URI deve estar no formato codificado por URL (codificado por porcentagem). Por exemplo,http://localhostéhttp%3A%2F%2Flocalhost.<state>com um número aleatório ou alguma informação codificada. Para ajudar a verificar a integridade da troca de informações, esse valor de estado deve corresponder ao que está na URL retornada posteriormente neste procedimento.
Não altere o
scopevalor do parâmetro. Ele representa a ID programática do Azure Databricks (2ff814a6-3304-4ab8-85cb-cd0e6f879c1d) junto com o escopo padrão (/.default, codificado por URL como%2f.default).Por exemplo:
https://login.microsoftonline.com/a1bc2d34-5e67-8f89-01ab-c2345d6c78de/oauth2/v2.0/authorize?client_id=12a34b56-789c-0d12-e3fa-b456789c0123 &response_type=code &redirect_uri=http%3A%2F%2Flocalhost &response_mode=query &scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default &state=12345Cole a URL como uma única linha em seu navegador da Web e, se solicitado, entre no Azure.
O código de
codeautorização está no campo no URL retornado. Salve o código de autorização em um local seguro. Além disso, verifique se o valor dostatecampo corresponde ao que você forneceu anteriormente neste procedimento.
O URL completo retornado terá esta aparência (com o valor de campo completo
codeencurtado para0.ASkAIj...RxgFhSAAaqui para brevidade):http://localhost/?code=0.ASkAIj...RxgFhSAA&state=12345&session_state=c44574d5-38ba-4f93-b2a3-a830db8e8cdfUse o código de autorização junto com
curlpara obter o token de acesso do Microsoft Entra ID.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 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default' \ -d 'code=<authorization-code>' \ -d 'redirect_uri=<redirect-uri>' \ -d 'grant_type=authorization_code' \ -d 'state=<state>'Substituir:
<tenant-id>com o ID de locatário do aplicativo registrado.<client-id>com o ID de cliente da aplicação registada.<authorization-code>com o seu código de autorização.<redirect-uri>com o URI de redirecionamento do aplicativo registrado. Esse URI deve estar no formato codificado por URL (porcentagem endossada). Por exemplo,http://localhostéhttp%3A%2F%2Flocalhost.<state>com um número aleatório ou alguma informação codificada. Para ajudar a verificar a integridade da troca de informações, esse valor de estado deve corresponder ao que está na carga útil de resposta mais adiante neste procedimento.
Não altere o
scopevalor do parâmetro. Ele representa a ID programática do Azure Databricks (2ff814a6-3304-4ab8-85cb-cd0e6f879c1d) junto com o escopo padrão (/.default, codificado por URL como%2f.default).Por exemplo:
curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \ https://login.microsoftonline.com/a1bc2d34-5e67-8f89-01ab-c2345d6c78de/oauth2/v2.0/token \ -d 'client_id=12a34b56-789c-0d12-e3fa-b456789c0123' \ -d 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default' \ -d 'code=0.ASkAIj...RxgFhSAA' \ -d 'redirect_uri=http%3A%2F%2Flocalhost' \ -d 'grant_type=authorization_code' \ -d 'state=12345'O token de ID do Microsoft Entra está no
access_tokenvalor dentro do resultado da chamada. Certifique-se de verificar se ostatevalor corresponde ao que você forneceu anteriormente neste procedimento.
Obter tokens de ID do Microsoft Entra usando a biblioteca MSAL Python
Recolha as seguintes informações:
Parâmetro Description ID de Inquilino do A ID de diretório (locatário) para o aplicativo relacionado registrado na ID do Microsoft Entra em Configurar um aplicativo no portal do Azure. ID de Cliente A ID do aplicativo (cliente) para o aplicativo relacionado registrado no Microsoft Entra ID. Este procedimento pressupõe que você tenha definido
http://localhostcomo o URI de redirecionamento para o aplicativo relacionado registrado no Microsoft Entra ID.Instale o SDK do MSAL Python em sua máquina local executando
pip install msalo .Salve o código a seguir como
get-tokens.pyem sua máquina local.# Given the client ID and tenant ID for an app registered in Azure, # provide a <ms-entra-id> access token and a refresh token. # If the caller is not already signed in to Azure, the caller's # web browser will prompt the caller to sign in first. # pip install msal from msal import PublicClientApplication import sys # You can hard-code the registered app's client ID and tenant ID here, # or you can provide them as command-line arguments to this script. client_id = '<client-id>' tenant_id = '<tenant-id>' # Do not modify this variable. It represents the programmatic ID for # Azure Databricks along with the default scope of '/.default'. scopes = [ '2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default' ] # Check for too few or too many command-line arguments. if (len(sys.argv) > 1) and (len(sys.argv) != 3): print("Usage: get-tokens.py <client ID> <tenant ID>") exit(1) # If the registered app's client ID and tenant ID are provided as # command-line variables, set them here. if len(sys.argv) > 1: client_id = sys.argv[1] tenant_id = sys.argv[2] app = PublicClientApplication( client_id = client_id, authority = "https://login.microsoftonline.com/" + tenant_id ) acquire_tokens_result = app.acquire_token_interactive( scopes = scopes ) if 'error' in acquire_tokens_result: print("Error: " + acquire_tokens_result['error']) print("Description: " + acquire_tokens_result['error_description']) else: print("Access token:\n") print(acquire_tokens_result['access_token']) print("\nRefresh token:\n") print(acquire_tokens_result['refresh_token'])Execute um dos seguintes procedimentos:
- No código anterior, substitua
<client-id>pelo ID do cliente do aplicativo registrado e<tenant-id>pelo ID do locatário do aplicativo registrado e execute o script, por exemplopython get-tokens.py. - Forneça a ID do cliente do aplicativo registrado e a ID do locatário do aplicativo registrado ao executar o script, por exemplo
python get-tokens.py 12a34b56-789c-0d12-e3fa-b456789c0123 a1bc2d34-5e67-8f89-01ab-c2345d6c78de.
- No código anterior, substitua
Se o navegador da Web solicitar, entre no Azure.
Os tokens de acesso e atualização do Microsoft Entra ID são impressos na saída.
Fluxo de nome de usuário-senha (programático)
Se tiver autoridade para iniciar sessão com um nome de utilizador e uma palavra-passe, reúna as seguintes informações:
Parâmetro Description ID de Inquilino do A ID de diretório (locatário) para o aplicativo relacionado registrado na ID do Microsoft Entra em Configurar um aplicativo no portal do Azure. ID de Cliente A ID do aplicativo (cliente) para o aplicativo realizado registrado no Microsoft Entra ID. Nome de utilizador e palavra-passe O nome de usuário (ou seja, o endereço de email quando você faz logon no portal do Azure) e a senha do usuário no locatário. Este procedimento pressupõe que você tenha definido
http://localhostcomo o URI de redirecionamento para o aplicativo relacionado registrado no Microsoft Entra ID.Instale o SDK do MSAL Python em sua máquina local executando
pip install msalo .Salve o código a seguir como
get-tokens-for-user.pyem sua máquina local.# Given the client ID and tenant ID for an app registered in Azure, # along with an Azure username and password, # provide a <ms-entra-id> access token and a refresh token. # If the caller is not already signed in to Azure, the caller's # web browser will prompt the caller to sign in first. # pip install msal from msal import PublicClientApplication import sys # You can hard-code the registered app's client ID and tenant ID here, # along with the Azure username and password, # or you can provide them as command-line arguments to this script. client_id = '<client-id>' tenant_id = '<tenant-id>' username = '<username>' password = '<password>' # Do not modify this variable. It represents the programmatic ID for # Azure Databricks along with the default scope of '/.default'. scope = [ '2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default' ] # Check for too few or too many command-line arguments. if (len(sys.argv) > 1) and (len(sys.argv) != 5): print("Usage: get-tokens-for-user.py <client ID> <tenant ID> <username> <password>") exit(1) # If the registered app's client ID and tenant ID along with the # Azure username and password are provided as command-line variables, # set them here. if len(sys.argv) > 1: client_id = sys.argv[1] tenant_id = sys.argv[2] username = sys.argv[3] password = sys.argv[4] app = PublicClientApplication( client_id = client_id, authority = "https://login.microsoftonline.com/" + tenant_id ) acquire_tokens_result = app.acquire_token_by_username_password( username = username, password = password, scopes = scope ) if 'error' in acquire_tokens_result: print("Error: " + acquire_tokens_result['error']) print("Description: " + acquire_tokens_result['error_description']) else: print("Access token:\n") print(acquire_tokens_result['access_token']) print("\nRefresh token:\n") print(acquire_tokens_result['refresh_token'])Execute um dos seguintes procedimentos:
- No código anterior, substitua
<client-id>pelo ID do cliente do aplicativo registrado,<tenant-id>pelo ID do locatário do aplicativo registrado,<username>pelo nome de usuário e<password>pela senha e, em seguida, execute o script, por exemplopython get-tokens-for-user.py. - Forneça o ID do cliente do aplicativo registrado, o ID do locatário do aplicativo registrado, o nome de usuário e a senha ao executar o script, por exemplo
python get-tokens-for-user.py 12a34b56-789c-0d12-e3fa-b456789c0123 a1bc2d34-5e67-8f89-01ab-c2345d6c78de someone@example.com "MyPa55w&rd!". Se um argumento de linha de comando contiver caracteres especiais, você deverá envolvê-lo com aspas.
- No código anterior, substitua
Os tokens de acesso e atualização do Microsoft Entra ID são impressos no seu terminal.
Use um token de acesso do Microsoft Entra ID para acessar a API REST do Databricks
Esta seção descreve como usar um token de acesso do Microsoft Entra ID para chamar a API REST do Databricks. Nos exemplos a seguir, substitua <access-token> pelo token de acesso do Microsoft Entra ID e <databricks-instance> pela URL por espaço de trabalho da sua implantação do Azure Databricks.
Exemplo de Python
Este exemplo mostra como listar os clusters em um espaço de trabalho do Azure Databricks.
import requests
import json
databricks_instance = '<databricks-instance>'
api_version = '/api/2.0'
api_command = '/clusters/list'
url = f"https://{databricks_instance}{api_version}{api_command}"
access_token = '<access-token>'
response = requests.get(
url = url,
headers = { 'Authorization': "Bearer " + access_token}
)
print(json.dumps(json.loads(response.text), indent = 2))
Nota
Se você for um usuário não administrador e quiser fazer logon como um usuário administrador, deverá fornecer o X-Databricks-Azure-Workspace-Resource-Id cabeçalho além do 'Authorization' : 'Bearer ' cabeçalho e deverá estar em uma função de Colaborador ou Proprietário no recurso de espaço de trabalho no Azure. Você constrói o valor da X-Databricks-Azure-Workspace-Resource-Id seguinte maneira:
# ...
subscription = '<azure-subscription-id>'
resource_group = '<azure-resource-group-name>'
workspace = '<databricks-workspace-name-in-azure>'
db_resource_id = '/subscriptions/%s/resourcegroups/%s/providers/microsoft.databricks/workspaces/%s' % (
subscription,
resource_group,
workspace
)
# ...
headers = {
'Authorization': "Bearer " + access_token,
'X-Databricks-Azure-Workspace-Resource-Id': db_resource_id
}
# ...
Para obter as informações de assinatura, recurso e espaço de trabalho no Azure, consulte Recursos abertos. Para abrir o recurso de destino, você pode pesquisar no tipo de serviço Azure Databricks e qualquer outra informação no Azure que você conheça sobre o espaço de trabalho do Azure Databricks de destino.
curl Exemplo
curl -X GET \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access-token>' \
https://<databricks-instance>/api/2.0/clusters/list
Atualizar um token de acesso do Microsoft Entra ID
Se você receber um token de atualização junto com seu token de acesso do Microsoft Entra ID, poderá usar o token de atualização para obter um novo token. Por padrão, o tempo de vida dos tokens de acesso do Microsoft Entra ID é um período de tempo aleatório entre 60 e 90 minutos (75 minutos em média). Você pode configurar o tempo de vida dos tokens de acesso do Microsoft Entra ID usando os métodos em Tempos de vida de token configuráveis no Microsoft Entra ID (anteriormente Azure Ative Directory).
O exemplo a seguir mostra como usar a biblioteca Python MSAL junto com um token de atualização para obter um novo token.
Salve o código a seguir como
refresh-tokens.pyem sua máquina local.# Given the client ID and tenant ID for an app registered in Azure, # along with a refresh token, provide a new <ms-entra-id> access token and # refresh token. # If the caller is not already signed in to Azure, the caller's # web browser will prompt the caller to sign in first. # pip install msal from msal import PublicClientApplication import sys # You can hard-code the registered app's client ID, tenant ID, # and refresh token here, or you can provide them as command-line # arguments to this script. client_id = '<client-id>' tenant_id = '<refresh-token' refresh_token = '<refresh-token>' # Do not modify this variable. It represents the programmatic ID for # Azure Databricks along with the default scope of '.default'. scope = [ '2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default' ] # Check for too few or too many command-line arguments. if (len(sys.argv) > 1) and (len(sys.argv) != 4): print("Usage: refresh-tokens.py <client ID> <tenant ID> <refresh token>") exit(1) # If the registered app's client ID, tenant ID, and refresh token are # provided as command-line variables, set them here. if len(sys.argv) > 1: client_id = sys.argv[1] tenant_id = sys.argv[2] refresh_token = sys.argv[3] app = PublicClientApplication( client_id = client_id, authority = "https://login.microsoftonline.com/" + tenant_id ) acquire_tokens_result = app.acquire_token_by_refresh_token( refresh_token = refresh_token, scopes = scope ) if 'error' in acquire_tokens_result: print("Error: " + acquire_tokens_result['error']) print("Description: " + acquire_tokens_result['error_description']) else: print("\nNew access token:\n") print(acquire_tokens_result['access_token']) print("\nNew refresh token:\n") print(acquire_tokens_result['refresh_token'])Execute um dos seguintes procedimentos:
- No código anterior, substitua
<client-id>pela ID do cliente do aplicativo registrado,<tenant-id>pela ID do locatário do aplicativo registrado e<refresh-token>pelo token de atualização e execute o script, por exemplopython get-tokens-for-user.py. - Forneça a ID do cliente do aplicativo registrado, a ID do locatário do aplicativo registrado e o token de atualização ao executar o script, por exemplo
python refresh-tokens.py 12a34b56-789c-0d12-e3fa-b456789c0123 a1bc2d34-5e67-8f89-01ab-c2345d6c78de "0.ASkAIj...huE84ALg". Se um argumento de linha de comando contiver caracteres especiais, você deverá envolvê-lo entre aspas.
- No código anterior, substitua
Os novos tokens de acesso e atualização do Microsoft Entra ID são impressos no seu terminal.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários