Obtenha o Microsoft Entra ID (anteriormente conhecido como Azure Active Directory) para usuários utilizando a MSAL
Importante
Este artigo descreve como criar manualmente tokens Microsoft Entra ID (anteriormente conhecido como Azure Active Directory) usando a MSAL (Biblioteca de Autenticação da Microsoft).
O Databricks não recomenda que você crie tokens do Microsoft Entra ID (antigo Azure Active Directory) para usuários do Azure Databricks manualmente. Isso ocorre porque cada token do Microsoft Entra ID tem curta duração, normalmente expirando em uma hora. Após esse tempo, você precisará gerar manualmente um token de substituição do Microsoft Entra ID. Em vez disso, use uma das ferramentas ou SDKs participantes que implementam o padrão de autenticação unificada do cliente Databricks. Essas ferramentas e SDKs geram e substituem automaticamente os tokens expirados do Microsoft Entra ID, aproveitando os seguintes tipos de autenticação da CLI do Azure.
As entidades de serviço gerenciadas do Azure Databricks são gerenciadas diretamente no Azure Databricks. As entidades de serviços gerenciadas do Microsoft Entra ID são gerenciadas no Microsoft Entra ID, o que requer permissões adicionais. O Databricks recomenda que você use as entidades de serviço gerenciadas do Azure Databricks para a maioria dos casos de uso. No entanto, o Databricks recomenda que você use as entidades de serviço gerenciadas do Microsoft Entra ID nos casos em que você precisa se autenticar no Azure Databricks e em outros recursos do Azure ao mesmo tempo.
Para criar uma entidade de serviço gerenciada do Azure Databricks em vez de uma entidade de serviço gerenciada do Microsoft Entra ID, consulte Gerenciar entidades de serviço.
Use a MSAL (Biblioteca de Autenticação da Microsoft) para adquirir tokens de acesso do Microsoft Entra ID por meio de programação. Este artigo descreve o uso básico da biblioteca MSAL e as entradas de usuário necessárias, com exemplos em Python.
Observação
A MSAL substitui a Biblioteca de Autenticação do Microsoft Entra ID (ADAL). Todo o suporte e desenvolvimento da Microsoft para a ADAL, incluindo correções de segurança, terminou em 30 de junho de 2022. Confira Migrar aplicativos para a MSAL (Biblioteca de Autenticação da Microsoft).
Dica
Talvez você queira tentar usar a CLI do Azure em vez da MSAL para obter tokens do Microsoft Entra ID para os usuários, pois usar a CLI do Azure envolve menos etapas. Confira Obtenha o Microsoft Entra ID (antigo Azure Active Directory) para usuários usando a CLI do Azure.
Defina também 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. Veja Obter tokens do Microsoft Entra ID (antigo Azure Active Directory) para entidades de serviço.
Configurar um aplicativo no portal do Azure
Registre um aplicativo no ponto de extremidade do Microsoft Entra ID no portal do Azure. Como alternativa, você pode usar um aplicativo do Microsoft Entra ID que já esteja registrado. Para obter mais informações, confira Registrar um aplicativo usando o portal do Azure.
Entre no portal do Azure.
Observação
O portal a ser usado é diferente dependendo se o aplicativo do Microsoft Entra ID é executado na nuvem pública do Azure ou em uma nuvem nacional ou soberana. Para obter mais informações, confira as 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.
Pesquise e selecione Microsoft Entra ID.
Em Gerenciar, selecione Registros de aplicativo > Novo registro.
Em Nome, insira um nome para o aplicativo.
Em Tipos de conta com suporte, selecione Somente contas deste diretório organizacional (Locatário único).
Na seção URI de Redirecionamento (opcional), em Selecionar uma plataforma, escolha Cliente público/nativo (móvel e desktop) e insira um URI de redirecionamento. No exemplo a seguir, o valor do URI de redirecionamento é
http://localhost.
Clique em Registrar.
Na página Visão geral do aplicativo, na seção Informações gerais, copie os seguintes valores:
- ID do Aplicativo (cliente)
- ID do Diretório (locatário)
- Em URIs de Redirecionamento, o URI de redirecionamento do cliente público que você já inseriu neste procedimento.
Adicione AzureDatabricks às permissões necessárias do aplicativo registrado. Você precisa ser um usuário administrador para executar esta etapa. Se encontrar um problema relacionado a permissões ao executar essa ação, entre em contato com o administrador para obter ajuda.
Na página Visão geral do aplicativo, na guia Introdução, clique em Exibir permissões de API.
Clique em Adicionar uma permissão.
No painel Solicitar permissões de API, clique na guia APIs usadas pela minha organização, procure AzureDatabricks e selecione-o.
Habilite a caixa de seleção user_impersonation e clique em Adicionar permissões.
Clique em Conceder consentimento do administrador para ### e em Sim. Para executar essa ação, você precisa ser um usuário administrador ou ter o privilégio de conceder o consentimento ao aplicativo. Se você não vir Conceder consentimento do administrador para ### ou se ignorar essa ação, precisará usar o Fluxo de código de autorização (interativo) na primeira vez que usar o aplicativo para fornecer consentimento. Depois disso, você poderá 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, veja Atribuir uma conta de usuário a um aplicativo empresarial para obter instruções do portal do Azure ou Atribuir usuários e grupos a um aplicativo no Microsoft Entra ID (antigo Azure Active 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ê precisará 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.
- Você não tiver consentimento no aplicativo registrado durante o registro do aplicativo.
Se você tiver a autoridade para entrar com um nome de usuário e uma 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.
- Solicitar um código de autorização, que inicia uma janela do navegador e solicita o logon do usuário do Azure. O código de autorização é retornado depois que o usuário faz logon 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 usada para concluir essas duas etapas é usar o navegador da Web e o cURL. Para fazer isso, use o navegador da Web para obter o código de autorização e use 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 do Python. Para fazer isso, execute um só script que usa o navegador da Web para obter o código de autorização e usa o código de autorização para obter um token de acesso e de atualização.
As duas abordagens pressupõem que você já esteja conectado ao Azure. Se você não estiver, seu navegador da Web solicitará a conexão.
Obter tokens do Microsoft Entra ID usando um navegador da Web e o curl
Reúna as seguintes informações:
Parâmetro Descrição ID do locatário A ID do Diretório (locatário) para o aplicativo relacionado registrado no Microsoft Entra ID em Configure um aplicativo do portal do Azure. ID do Cliente A ID do Aplicativo (cliente) referente ao aplicativo registrado no Microsoft Entra ID. URI de redirecionamento Os URIs de Redirecionamento apropriados do aplicativo registrado no Microsoft Entra ID (por exemplo, http://localhost). As respostas de autenticação são enviadas para esse 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é a URL a seguir. Substitua os campos no exemplo de URL a seguir de acordo. Observe que a URL precisa ser enviada como uma só linha. Quebras de linha foram adicionadas à URL a seguir para melhor leitura. Para saber mais, confira 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>Substitua:
<tenant-id>pela ID de locatário do aplicativo registrado.<client-id>pela ID de cliente do aplicativo registrado.<redirect-uri>com o URI de redirecionamento do aplicativo registrado. Esse URI precisa estar no formato codificado em URL (codificado em percentual). Por exemplo,http://localhostéhttp%3A%2F%2Flocalhost.<state>com um número aleatório ou algumas informações codificadas. 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 valor do parâmetro
scope. Ela representa a ID programática para o Azure Databricks (2ff814a6-3304-4ab8-85cb-cd0e6f879c1d) com o escopo padrão (/.default, codificado em 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 só linha no navegador da Web e, se solicitado, entre no Azure.
O código de autorização está no campo
codena URL retornada. Salve o código de autorização em um local seguro. Além disso, verifique se o valor do campostatecorresponde ao que você forneceu anteriormente neste procedimento.
A URL retornada completa terá esta aparência (com o valor de campo
codecompleto reduzido para0.ASkAIj...RxgFhSAAaqui para fins de brevidade):http://localhost/?code=0.ASkAIj...RxgFhSAA&state=12345&session_state=c44574d5-38ba-4f93-b2a3-a830db8e8cdfUse o código de autorização 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>'Substitua:
<tenant-id>pela ID de locatário do aplicativo registrado.<client-id>pela ID de cliente do aplicativo registrado.<authorization-code>com o código de autorização.<redirect-uri>com o URI de redirecionamento do aplicativo registrado. Esse URI precisa estar no formato codificado em URL (codificado em percentual). Por exemplo,http://localhostéhttp%3A%2F%2Flocalhost.<state>com um número aleatório ou algumas informações codificadas. Para ajudar a verificar a integridade da troca de informações, esse valor de estado deve corresponder ao que está no conteúdo da resposta posteriormente neste procedimento.
Não altere o valor do parâmetro
scope. Ela representa a ID programática para o Azure Databricks (2ff814a6-3304-4ab8-85cb-cd0e6f879c1d) com o escopo padrão (/.default, codificado em 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 do Microsoft Entra ID está no valor
access_tokendentro do resultado da chamada. Verifique se o valorstatecorresponde ao que você forneceu anteriormente neste procedimento.
Obtenha tokens do Microsoft Entra ID usando a biblioteca do MSAL Python
Reúna as seguintes informações:
Parâmetro Descrição ID do locatário A ID do Diretório (locatário) para o aplicativo relacionado registrado no Microsoft Entra ID em Configure um aplicativo do portal do Azure. ID do Cliente A ID do Aplicativo (cliente) referente ao aplicativo registrado no Microsoft Entra ID. Este procedimento presume que você tenha definido
http://localhostcomo o URI de Redirecionamento para o aplicativo relacionado registrado no Microsoft Entra ID.Instale o SDK da MSAL do Python no computador local executando
pip install msal.Salve o código a seguir como
get-tokens.pyno computador 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'])Realize um dos seguintes procedimentos:
- No código anterior, substitua
<client-id>pela ID do cliente e<tenant-id>pela ID de locatário do aplicativo registrado e execute o script, por exemplo,python get-tokens.py. - Forneça a ID do cliente e a ID de locatário do aplicativo registrado quando 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 a conexão, entre no Azure.
Os tokens de acesso e de atualização do Microsoft Entra ID são impressos na saída.
Fluxo de nome de usuário/senha (programático)
Se você tiver a autoridade para entrar com um nome de usuário e uma senha, reúna as seguintes informações:
Parâmetro Descrição ID do locatário A ID do Diretório (locatário) para o aplicativo relacionado registrado no Microsoft Entra ID em Configure um aplicativo do portal do Azure. ID do Cliente A ID do Aplicativo (cliente) referente ao aplicativo registrado no Microsoft Entra ID. Nome de usuário e senha O nome de usuário (ou seja, o endereço de email usado para logon no portal do Azure) e a senha do usuário no locatário. Este procedimento presume que você tenha definido
http://localhostcomo o URI de Redirecionamento para o aplicativo relacionado registrado no Microsoft Entra ID.Instale o SDK da MSAL do Python no computador local executando
pip install msal.Salve o código a seguir como
get-tokens-for-user.pyno computador 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'])Realize um dos seguintes procedimentos:
- No código anterior, substitua
<client-id>pela ID do cliente do aplicativo registrado,<tenant-id>pela ID de locatário do aplicativo registrado,<username>pelo nome de usuário e<password>pela senha e execute o script, por exemplo,python get-tokens-for-user.py. - Forneça a ID do cliente do aplicativo registrado, a ID de locatário do aplicativo registrado, o nome de usuário e a senha quando 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, coloque-o entre aspas.
- No código anterior, substitua
Os novos tokens de acesso e de atualização do Microsoft Entra ID são impressos no terminal.
Usar 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 workspace da implantação do Azure Databricks.
Exemplo de Python
Este exemplo mostra como listar os clusters de um workspace 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))
Observação
Se você for um usuário não administrador e quiser fazer logon como um usuário administrador, precisará fornecer o cabeçalho X-Databricks-Azure-Workspace-Resource-Id, além do cabeçalho 'Authorization' : 'Bearer ', e estar em uma função Colaborador ou Proprietário no recurso de workspace no Azure. Construa o valor X-Databricks-Azure-Workspace-Resource-Id da seguinte forma:
# ...
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, de recurso e de workspace no Azure, confira Abrir recursos. Para abrir o recurso de destino, procure o tipo de serviço Azure Databricks e todas as outras informações no Azure que você sabe sobre o workspace de destino do Azure Databricks.
Exemplo do curl
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 com o token de acesso do Microsoft Entra ID, use 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 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 descritos em Tempos de vida de token configuráveis no Microsoft Entra ID (antigo Azure Active Directory).
O exemplo a seguir mostra como usar a biblioteca MSAL do Python com um token de atualização para obter um novo token.
Salve o código a seguir como
refresh-tokens.pyno computador 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'])Realize um dos seguintes procedimentos:
- No código anterior, substitua
<client-id>pela ID do cliente do aplicativo registrado,<tenant-id>pela ID de locatário do aplicativo registrado e<refresh-token>pelo token de atualização e execute o script, por exemplo,python get-tokens-for-user.py. - Forneça a ID do cliente e a ID de locatário do aplicativo registrado, além do token de atualização, quando 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, coloque-o entre aspas.
- No código anterior, substitua
Os novos tokens de acesso e de atualização do Microsoft Entra ID são impressos no terminal.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de