Obter tokens de ID do Microsoft Entra para entidades de serviço

Importante

Esta seção descreve como obter manualmente tokens do Microsoft Entra ID para entidades de serviço.

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.

O Databricks não recomenda criar manualmente tokens do Microsoft Entra ID para entidades de serviço do Microsoft Entra ID. 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 do Databricks:

• Autenticação de identidades gerenciadas do Azure
• Autenticação da entidade de serviço do MS Entra
• Autenticação da CLI do Azure

Se você não tiver uma entidade de serviço, poderá provisionar uma seguindo um destes conjuntos de instruções:

• Provisionar uma entidade de serviço no portal do Azure
• Provisionar uma entidade de serviço com a CLI do Azure

Este artigo descreve como uma entidade de serviço definida no Microsoft Entra ID, poderá também atuar como uma entidade de segurança na qual as políticas de autenticação e autorização podem ser impostas no Azure Databricks. As entidades de serviço em um workspace do Azure Databricks podem ter um controle de acesso refinado diferente dos usuários normais (entidades de usuário).

Uma entidade de serviço atua como uma função de cliente e usa o fluxo de credenciais do cliente do OAuth 2.0 para autorizar o acesso a recursos do Azure Databricks.

Você pode gerenciar entidades de serviço no Databricks ou usando o procedimento a seguir do portal do Azure.

Também é possível usar a MSAL (Biblioteca de Autenticação da Microsoft) para obter programaticamente um token de acesso do Microsoft Entra ID, para um usuário em vez de uma entidade de serviço. Consulte Obter tokens do Microsoft Entra ID para usuários usando a MSAL.

Provisionar uma entidade de serviço no 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 você quer provisionar a entidade de serviço.

3. Em Pesquisa de recursos, serviços e documentos, pesquise e selecione Microsoft Entra ID.

4. Clique em + Adicionar e selecione Registro do aplicativo.

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. Clique em Registrar.

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

9. Para gerar um segredo do cliente, em Gerenciar, clique em Certificados e segredos.

   Observação

   Você usa esse segredo do cliente para gerar os tokens do Microsoft Entra ID para autenticação de entidades de serviço do Microsoft Entra ID com o Azure Databricks. Para determinar se uma ferramenta ou SDK do Azure Databricks pode usar tokens do Microsoft Entra ID, consulte a documentação da ferramenta ou do SDK.

10. Na guiaSegredos do cliente, clique em Novo segredo do cliente.

    

11. No painel Adicionar um segredo do cliente, em Descrição, insira uma descrição para o segredo do cliente.

12. Em Expirar, selecione um prazo de expiração para o segredo do cliente e clique em Adicionar.

13. Copie e armazene o Valor do segredo do cliente em um local seguro, pois esse segredo do cliente é a senha para seu aplicativo.

Provisionar uma entidade de serviço com a CLI do Azure

Veja Criar uma entidade de serviço do Microsoft Entra ID (antigo Azure Active Directory) com a CLI do Azure.

Obter um token de acesso do Microsoft Entra ID com a API REST da plataforma de identidade da Microsoft

Importante

Esta seção descreve como obter manualmente um token do Microsoft Entra ID para uma entidade de serviço usando a API REST da plataforma de identidade da Microsoft.

O Databricks não recomenda criar manualmente tokens do Microsoft Entra ID para entidades de serviço do Microsoft Entra ID. 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 do Databricks:

• Autenticação de identidades gerenciadas do Azure
• Autenticação da entidade de serviço do MS Entra
• Autenticação da CLI do Azure

Para acessar a API REST do Databricks com a entidade de serviço, receba e use um token de acesso do Microsoft Entra ID para a entidade de serviço. Para saber mais, confira Primeiro caso: solicitação de token de acesso com um segredo compartilhado.

Dica

Também é possível usar a CLI do Azure para receber o token de acesso do Microsoft Entra ID. Consulte Receber um token de acesso do Microsoft Entra ID com a CLI do Azure.

1. Reúna as seguintes informações:

   Parâmetro	Descrição
   Tenant ID	O Directory (tenant) ID do aplicativo relacionado registrado no Microsoft Entra ID.
   Client ID	O Application (client) ID do aplicativo relacionado registrado no Microsoft Entra ID.
   Client secret	O Value do segredo do cliente para o aplicativo relacionado registrado no Microsoft Entra ID.

2. Use as informações anteriores junto com o curl para receber 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 'grant_type=client_credentials' \
   -d 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default' \
   -d 'client_secret=<client-secret>'
   

   Substitua:

   • <tenant-id> pela ID de locatário do aplicativo registrado.
   • <client-id> pela ID de cliente do aplicativo registrado.
   • <client-secret> pelo valor de segredo do cliente do aplicativo registrado.

   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 'grant_type=client_credentials' \
   -d 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default' \
   -d 'client_secret=abc1D~Ef...2ghIJKlM3'
   

   O token de acesso do Microsoft Entra ID está no valor access_token na saída da chamada.

Receber um token de acesso do Microsoft Entra ID com a CLI do Azure

Importante

Esta seção descreve como receber manualmente um token do Microsoft Entra ID para uma entidade de serviço usando a CLI do Azure.

O Databricks não recomenda criar manualmente tokens do Microsoft Entra ID para entidades de serviço do Microsoft Entra ID. 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 do Databricks:

• Autenticação de identidades gerenciadas do Azure
• Autenticação da entidade de serviço do MS Entra
• Autenticação da CLI do Azure

Para acessar a API REST do Databricks com a entidade de serviço, receba e use um token de acesso do Microsoft Entra ID para a entidade de serviço.

1. Reúna as seguintes informações:

   Parâmetro	Descrição
   Tenant ID	O Directory (tenant) ID do aplicativo relacionado registrado no Microsoft Entra ID.
   Client ID	O Application (client) ID do aplicativo relacionado registrado no Microsoft Entra ID.
   Client secret	O Value do segredo do cliente para o aplicativo relacionado registrado no Microsoft Entra ID.

2. Obtenha a ID da assinatura correta do Azure para a entidade de serviço do Microsoft Entra ID, se você ainda não conhece essa ID, fazendo um dos seguintes procedimentos:

   • Na barra de navegação superior do workspace do Azure Databricks, clique em seu nome de usuário e, em seguida, no Portal do Azure. Na página de recursos do workspace do Azure Databricks exibida, clique em Visão geral na barra lateral. Em seguida, procure o campo ID da Assinatura, que contém a ID da assinatura.

   • Use a CLI do Azure para executar o comando az databricks workspace list, usando as opções --query e -o ou --output para restringir os resultados. Substitua adb-0000000000000000.0.azuredatabricks.net pelo nome da instância do workspace, sem incluir o https://. Neste exemplo, o 00000000-0000-0000-0000-000000000000 após /subscriptions/ na saída é a ID da assinatura.

     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
     

     Se a seguinte mensagem é exibida, você está conectado ao locatário errado: The subscription of '<subscription-id>' doesn't exist in cloud 'AzureCloud'. para entrar no locatário correto, execute o comando az login novamente usando a opção -t ou --tenant para especificar a ID de locatário correta.

     Você pode obter a ID do locatário de um workspace do Azure Databricks executando o comando curl -v <per-workspace-URL>/aad/auth e examinando a saída < location: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000, em que 00000000-0000-0000-0000-000000000000 é a ID do locatário. Veja também Obter IDs de assinatura e locatário no portal do Azure.

     az login -t <tenant-id>
     

3. Depois de ter a ID de locatário do Azure, a ID do cliente, o segredo do cliente e a ID da assinatura corretos da entidade de serviço do Microsoft Entra ID, entre no Azure usando a CLI do Azure para executar o comando az login. Use a opção --service-principal juntamente com a especificação dos valores para os parâmetros de Tenant ID (Directory (tenant) ID), Client ID (Application (client) ID) e Client secret (Value) para o aplicativo relacionado registrado no Microsoft Entra ID.

   az login \
   --service-principal \
   -t <Tenant-ID> \
   -u <Client-ID> \
   -p <Client-secret>
   

4. Confirme se você entrou na assinatura correta para sua entidade de serviço do Microsoft Entra ID conectada. Para fazer isso, execute o comando az account set, usando a opção -s ou --subscription para especificar a ID da assinatura correta.

   az account set -s <subscription-id>
   

5. Gere o token de acesso do Microsoft Entra ID para a entidade de serviço do Microsoft Entra ID assinada, executando o comando az account get-access-token. Use a opção --resource para especificar a ID de recurso exclusiva para o serviço do Azure Databricks, que é 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d. Exiba apenas o valor do token do Microsoft Entra ID na saída do comando usando as opções --query, -o ou --output.

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

Usar o token de acesso do Microsoft Entra ID da entidade de serviço para acessar a API REST do Databricks

Importante

Esta seção descreve como usar curl e o token de acesso do Microsoft Entra ID de uma entidade de serviço para acessar a API REST do Databricks.

Em vez de curl, você pode usar uma das ferramentas ou SDKs participantes que implementam o padrão Autenticação unificada do cliente do Databricks. Essas ferramentas e SDKs também geram e substituem automaticamente os tokens expirados do Microsoft Entra ID, aproveitando os seguintes tipos de autenticação do Databricks:

• Autenticação de identidades gerenciadas do Azure
• Autenticação da entidade de serviço do MS Entra
• Autenticação da CLI do Azure

Uma entidade de serviço que é um usuário do Databricks pode se autenticar na API REST do Databricks com os tokens do Microsoft Entra ID.

Uma entidade de serviço também poderá se adicionar como administrador de workspace a um workspace se tiver a função Colaborador ou Proprietário no recurso de workspace de destino no Azure. Se a entidade de serviço for um Colaborador ou Proprietário no workspace de destino e você pretender adicioná-la a um workspace com o token do Microsoft Entra ID, acesse Acesso à API no nível do workspace para entidades de serviço que não são usuários do Azure Databricks.

Caso contrário, continuar para Acesso à API para entidades de serviço que são usuários e administradores do Azure Databricks.

Acesso à API para entidades de serviço que são usuários e administradores do Azure Databricks

Para concluir esse procedimento, primeiro adicione a entidade de serviço ao workspace ou conta do Azure Databricks. Você pode adicionar sua entidade de serviço diretamente à sua conta, sem conceder a ela acesso ao workspace, usando a API do SCIM (Conta).

Você pode adicionar sua entidade de serviço a um workspace usando o ponto de extremidade da API de Entidades de Serviço. Isso também adicionará a entidade de serviço à sua conta do Azure Databricks. Por exemplo:

Usando a CLI do Databricks versão 0.205 ou superior (recomendado):

Adicione a entidade de serviço:

databricks service-principals create --application-id 12a34b56-789c-0d12-e3fa-b456789c0123 --display-name "My Service Principal" -p <profile-name-that-references-calling-users-access-token>

Atualize os direitos do workspace da entidade de serviço:

databricks service-principals patch 1234567890123456 --json @update-service-principal.json -p <profile-name-that-references-access-token>

update-service-principal.json:

{
  "Operations": [
    {
      "op": "add",
      "path": "entitlements",
      "value": {
        "value": "workspace-acccess",
        "value": "allow-cluster-create",
        "value": "databricks-sql-access"
      }
    }
  ],
  "schema": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ]
}

Consulte Autenticação da CLI do Databricks.

Usando curl:

curl -X POST \
-H 'Authorization: Bearer <access-token>' \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/preview/scim/v2/ServicePrincipals \
-H 'Content-type: application/scim+json' \
-d @create-service-principal.json

create-service-principal.json:

{
  "displayName": "My Service Principal",
  "applicationId": "12a34b56-789c-0d12-e3fa-b456789c0123",
  "entitlements": [
    {
      "value": "allow-cluster-create"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal"
  ],
  "active": true
}

Pule para o Acesso à API em nível de workspace para entidades de serviço que não são usuários do Azure Databricks se uma das seguintes condições for verdadeira:

• A API REST do Azure Databricks que você quer chamar exige acesso de administrador ao workspace e a entidade de serviço é um membro do workspace, mas não tem acesso de administrador ao workspace no momento.
• A entidade de serviço ainda não foi adicionada ao workspace do Azure Databricks de destino.

1. Reúna as seguintes informações.

   Parâmetro	Descrição
   Token de acesso do Microsoft Entra ID	O token de acesso do Microsoft Entra ID retornado da solicitação em Obter um token de acesso do Microsoft Entra ID com a API REST da plataforma de identidade da Microsoft ou Obter um token de acesso do Microsoft Entra ID com a CLI do Azure.

2. Use o token de acesso do Microsoft Entra ID junto com curl, para chamar a API REST do Databricks. Por exemplo:

   Usando a CLI do Databricks versão 0.205 ou superior (recomendado):

   databricks clusters list -p <profile-name-that-references-azure-ad-access-token>
   

   Consulte Autenticação da CLI do Databricks.

   Usando curl:

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

   Substitua:

   • <access-token> com o token de acesso do Microsoft Entra ID.
   • <databricks-instance> pela URL por workspace de sua implantação do Azure Databricks.
   • GET e /api/2.0/clusters/list pela operação HTTP apropriada e o ponto de extremidade da API REST do Databricks de destino.

   Por exemplo:

   curl -X GET \
   -H 'Authorization: Bearer <access-token>' \
   https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/list
   

Acesso à API em nível de workspace para entidades de serviço que são usuários do Azure Databricks

Siga esse procedimento se uma das seguintes condições for verdadeira:

• A API REST do Azure Databricks que você quer chamar exige acesso de administrador ao workspace e a entidade de serviço é um membro do workspace, mas não tem acesso de administrador ao workspace no momento.
• A entidade de serviço ainda não foi adicionada ao workspace do Azure Databricks de destino.

Requisitos:

• A entidade de serviço exige a função Colaborador ou Proprietário no recurso do workspace de destino no Azure.

1. Reúna as seguintes informações:

   Parâmetro	Descrição
   ID do locatário	A ID do diretório (locatário) do aplicativo relacionado registrado no Microsoft Entra ID em Provisionar uma entidade de serviço no portal do Azure.
   ID do Cliente	A ID do Aplicativo (cliente) referente ao aplicativo registrado no Microsoft Entra ID.
   Segredo do cliente	O Valor do segredo do cliente para o aplicativo relacionado registrado no Microsoft Entra ID, criado em Provisionar uma entidade de serviço no portal do Azure.
   Token de acesso do Microsoft Entra ID	O token de acesso do Microsoft Entra ID retornado da solicitação em Obter um token de acesso do Microsoft Entra ID com a API REST da plataforma de identidade da Microsoft ou Obter um token de acesso do Microsoft Entra ID com a CLI do Azure.
   ID da assinatura	A ID (não o nome) da assinatura do Azure associada ao workspace de destino do Azure Databricks. Para obtê-la, junto com as informações a seguir, 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.
   Nome do grupo de recursos	O nome do grupo de recursos do Azure associado ao workspace de destino do Azure Databricks.
   Nome do workspace	O nome do workspace de destino do Azure Databricks no Azure.

2. Use algumas das informações anteriores com curl para obter um token de acesso de ponto de extremidade de gerenciamento do Microsoft Entra ID.

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

   Substitua:

   • <tenant-id> pela ID de locatário do aplicativo registrado.
   • <client-id> pela ID de cliente do aplicativo registrado.
   • <client-secret> pelo valor de segredo do cliente do aplicativo registrado.

   Não altere o valor do parâmetro resource. Ele representa o ponto de extremidade de gerenciamento do Microsoft Entra ID (https://management.core.windows.net/, codificado em URL como https%3A%2F%2Fmanagement.core.windows.net%2F).

   Por exemplo:

   curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
   https://login.microsoftonline.com/a1bc2d34-5e67-8f89-01ab-c2345d6c78de/oauth2/token \
   -d 'client_id=12a34b56-789c-0d12-e3fa-b456789c0123' \
   -d 'grant_type=client_credentials' \
   -d 'resource=https%3A%2F%2Fmanagement.core.windows.net%2F' \
   -d 'client_secret=abc1D~Ef...2ghIJKlM3'
   

   O token de acesso do ponto de extremidade de gerenciamento do Microsoft Entra ID está no valor access_token, dentro da saída da chamada.

3. Use o token de acesso do ponto de extremidade de gerenciamento do Microsoft Entra ID, junto ao restante das informações anteriores e curl para chamar a API REST do Databricks, por exemplo:

    curl -X GET \
    -H 'Authorization: Bearer <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
   

   Substitua:

   • <access-token> com o token de acesso do Microsoft Entra ID.

     • <management-access-token> com o token de acesso do ponto de extremidade de gerenciamento do Microsoft Entra ID.
     • <subscription-id> pela ID da assinatura associada ao workspace de destino do Azure Databricks.
     • <resource-group-name> pelo nome do grupo de recursos associado ao workspace de destino do Azure Databricks.
     • <workspace-name> pelo nome do workspace de destino do Azure Databricks.
     • <databricks-instance> pela URL por workspace de sua implantação do Azure Databricks.
     • GET e /api/2.0/clusters/list pela operação HTTP apropriada e o ponto de extremidade da API REST do Databricks de destino.

     Por exemplo:

     curl -X GET \
     -H 'Authorization:Bearer <access-token>' \
     -H 'X-Databricks-Azure-SP-Management-Token: abC1dE...ghIj23kl' \
     -H 'X-Databricks-Azure-Workspace-Resource-Id: /subscriptions/12a345...bcd6789e/resourceGroups/my-resource-group/providers/Microsoft.Databricks/workspaces/my-workspace' \
     https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/list
     

   Após a autenticação no workspace, a entidade de serviço se torna um administrador do workspace do Azure Databricks e não precisa mais da função Colaborador ou Proprietário para acessar o workspace.