Obter tokens do Microsoft Entra ID para usuários usando MSAL

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.

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.

1. 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.

2. 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.

3. Pesquise e selecione Microsoft Entra ID.

4. Em Gerenciar, selecione Registros de aplicativo > Novo registro.

5. Em Nome, insira um nome para o aplicativo.

6. Em Tipos de conta com suporte, selecione Somente contas deste diretório organizacional (Locatário único).

7. 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.

   

8. Clique em Registrar.

9. 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.

   

10. 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.

    1. Na página Visão geral do aplicativo, na guia Introdução, clique em Exibir permissões de API.

       

    2. Clique em Adicionar uma permissão.

       

    3. No painel Solicitar permissões de API, clique na guia APIs usadas pela minha organização, procure AzureDatabricks e selecione-o.

       

    4. Habilite a caixa de seleção user_impersonation e clique em Adicionar permissões.

       

    5. 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:

• Fluxo de código de autorização (interativo)
• Fluxo de nome de usuário/senha (programático)

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.

1. 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.
2. 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

1. 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.

2. 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=12345
   

3. Cole a URL como uma só linha no navegador da Web e, se solicitado, entre no Azure.

   

4. O código de autorização está no campo code na URL retornada. Salve o código de autorização em um local seguro. Além disso, verifique se o valor do campo state corresponde ao que você forneceu anteriormente neste procedimento.

   

   A URL retornada completa terá esta aparência (com o valor de campo code completo reduzido para 0.ASkAIj...RxgFhSAA aqui para fins de brevidade):

   http://localhost/?code=0.ASkAIj...RxgFhSAA&state=12345&session_state=c44574d5-38ba-4f93-b2a3-a830db8e8cdf
   

5. Use o código de autorização com curl para 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_token dentro do resultado da chamada. Verifique se o valor state corresponde ao que você forneceu anteriormente neste procedimento.

Obtenha tokens do Microsoft Entra ID usando a biblioteca do MSAL Python

1. 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://localhost como o URI de Redirecionamento para o aplicativo relacionado registrado no Microsoft Entra ID.

2. Instale o SDK da MSAL do Python no computador local executando pip install msal.

3. Salve o código a seguir como get-tokens.py no 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'])
   

4. 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.

5. Se o navegador da Web solicitar a conexão, entre no Azure.

6. 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)

1. 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://localhost como o URI de Redirecionamento para o aplicativo relacionado registrado no Microsoft Entra ID.

2. Instale o SDK da MSAL do Python no computador local executando pip install msal.

3. Salve o código a seguir como get-tokens-for-user.py no 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'])
   

4. 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.

5. 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))

# ...

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
  }

# ...

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.

1. Salve o código a seguir como refresh-tokens.py no 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'])
   

2. 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.

3. Os novos tokens de acesso e de atualização do Microsoft Entra ID são impressos no terminal.