Executar um trabalho com uma entidade de serviço do Microsoft Entra ID

Artigo
05/28/2024

Os trabalhos fornecem uma forma não interativa de executar aplicativos em um cluster do Azure Databricks, por exemplo, um trabalho ETL ou uma tarefa de análise de dados que deve ser executada de acordo com um agendamento. Normalmente, esses trabalhos são executados como o usuário que os criou, mas isso pode ter algumas limitações:

A criação e a execução de trabalhos dependem de o usuário ter as permissões apropriadas.
Somente o usuário que criou o trabalho tem acesso a ele.
O usuário pode ser removido do workspace do Azure Databricks.

O uso de uma conta de serviço (uma conta associada a um aplicativo em vez de um usuário específico) é um método comum para resolver essas limitações. No Azure, você pode usar uma entidade de serviço e aplicativo do Microsoft Entra ID (anteriormente Azure Active Directory) para criar uma conta de serviço.

Um exemplo de uma situação em que isso é importante é quando as entidades de serviço controlam o acesso aos dados armazenados em uma conta do Azure Data Lake Storage Gen2. A execução de trabalhos com essas entidades de serviço permite que os trabalhos acessem dados na conta de armazenamento e fornece controle sobre o escopo de acesso a dados.

Esse tutorial descreve como criar uma entidade de serviço e um aplicativo do Microsoft Entra ID e tornar essa entidade de serviço o proprietário de um trabalho. Você também aprenderá a conceder permissões para executar um trabalho a outros grupos que não são os proprietários do trabalho. Veja uma visão geral de alto nível das tarefas descritas neste tutorial:

Crie uma entidade de serviço no Microsoft Entra ID.
Criar um PAT (token de acesso pessoal) no Azure Databricks. Você usará o PAT para se autenticar na API REST do Databricks.
Adicionar a entidade de serviço como um usuário não administrativo ao Azure Databricks usando a API do SCIM do Databricks.
Criar um escopo de segredo com suporte do Azure Key Vault no Azure Databricks.
Conceder à entidade de serviço acesso de leitura ao escopo do segredo.
Criar um trabalho no Azure Databricks e configurar o cluster de trabalho para ler segredos no escopo do segredo.
Transferir a propriedade do trabalho para a entidade de serviço.
Testar o trabalho executando-o como a entidade de serviço.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita antes de começar.

Observação

Não é possível usar um cluster com passagem de credenciais habilitada para executar um trabalho pertencente a uma entidade de serviço. Se o seu trabalho exigir que uma entidade de serviço acesse o armazenamento do Azure, confira Conectar-se ao Azure Data Lake Storage Gen2 ou ao Armazenamento de Blobs usando as credenciais do Azure.

Requisitos

Você precisará do seguinte para este tutorial:

Uma conta de usuário com as permissões necessárias para registrar um aplicativo no seu locatário do Microsoft Entra ID.
Privilégios administrativos no workspace do Azure Databricks em que você executará trabalhos.
Uma ferramenta para fazer solicitações de API para o Azure Databricks. Este tutorial usa o cURL, mas você pode usar qualquer ferramenta que permita enviar solicitações de API REST.

Criar uma entidade de serviço no Microsoft Entra ID

Uma entidade de serviço é a identidade de um aplicativo do Microsoft Entra ID. Para criar a entidade de serviço que será usada para executar trabalhos:

No portal do Azure, selecione Microsoft Entra ID > Registros de aplicativo > Novo registro. Insira um nome para o aplicativo e clique em Registrar.
Acesse Certificados e segredos, clique em Novo segredo do cliente e gere um segredo do cliente. Copie e salve o segredo em um local seguro.
Acesse Visão geral e anote a ID do Aplicativo (cliente) e a ID do Diretório (locatário).

Criar o token de acesso pessoal do Azure Databricks

Você usará um PAT (token de acesso pessoal) do Azure Databricks para se autenticar na API REST do Databricks. Para criar um PAT que possa ser usado para fazer solicitações de API:

Acesse o workspace do Azure Databricks.
Clique no ícone de usuário no canto superior direito da tela e em Configurações.
Clique em Desenvolvedor.
Ao lado de Tokens de acesso, clique em Gerenciar.
Clique em Gerar Novo Token.
Copie e salve o valor do token.

Dica

Esse exemplo usa um token de acesso pessoal, mas você pode usar um token do Microsoft Entra ID para a maioria das APIs. Uma melhor prática é que um PAT é adequado para tarefas de configuração administrativa, mas os tokens do Microsoft Entra ID são preferidos para cargas de trabalho de produção.

Você pode restringir a geração de PATs aos administradores apenas para fins de segurança. Consulte Monitorar e gerenciar tokens de acesso pessoal para obter mais detalhes.

Adicionar a entidade de serviço ao workspace do Azure Databricks

Adicione a entidade de serviço do Microsoft Entra ID a um workspace usando a API de Entidades de Serviço. Você também precisa conceder à entidade de serviço permissão para iniciar clusters de trabalho automatizados. Conceda isso por meio da permissão allow-cluster-create. Abra um terminal e use a CLI do Databricks para executar o seguinte comando para adicionar a entidade de serviço e conceder as permissões necessárias:

databricks service-principals create --json '{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal"
  ],
  "applicationId":"<application-id>",
  "displayName": "test-sp",
  "entitlements":[
    {
      "value":"allow-cluster-create"
    }
  ]
}'

Substitua <application-id> com Application (client) ID para o registro de aplicativo do aplicativo Microsoft Entra ID.

Criar um escopo de segredo com suporte do Azure Key Vault no Azure Databricks

Os escopos de segredos fornecem armazenamento seguro e gerenciamento de segredos. Você armazenará o segredo associado à entidade de serviço em um escopo de segredo. Você pode armazenar segredos em um escopo de segredo do Azure Databricks ou em um escopo de segredo com suporte do Azure Key Vault. Estas instruções descrevem a opção com suporte do Azure Key Vault:

Crie uma instância do Azure Key Vault no portal do Azure.
Crie o escopo de segredo do Azure Databricks com suporte da instância do Azure Key Vault.

Etapa 1: Criar uma instância do Azure Key Vault

No portal do Azure, selecione Cofres de Chaves > + Adicionar e dê um nome ao Cofre de Chaves.
Clique em Revisar + Criar.
Após a conclusão da validação, clique em Criar.
Depois de criar o Cofre de Chaves, acesse a página Propriedades para o novo Cofre de Chaves.
Copie e salve o URI do Cofre e a ID do Recurso.

Etapa 2: Criar um escopo de segredo com suporte do Azure Key Vault

Os recursos do Azure Databricks podem referenciar segredos armazenados em um Azure Key Vault criando um escopo de segredo com suporte do Cofre de Chaves. Para criar o escopo de segredo do Azure Databricks:

Acesse a página Criar Escopo de Segredo do Azure Databricks em https://<per-workspace-url>/#secrets/createScope. Substitua per-workspace-url pela URL exclusiva por workspace do seu workspace do Azure Databricks.
Insira um Nome de Escopo.
Insira os valores do URI do Cofre e da ID do Recurso para o Azure Key Vault criado na Etapa 1: Criar uma instância do Azure Key Vault.
Clique em Criar.

Salvar o segredo do cliente no Azure Key Vault

No portal do Azure, acesse o serviço Cofres de chaves.
Selecione o Cofre de Chaves criado na Etapa 1: Criar uma instância do Azure Key Vault.
Em Configurações > Segredos, clique em Gerar/Importar.
Selecione a opção de upload Manual e insira o segredo do cliente no campo Valor.
Clique em Criar.

Conceder à entidade de serviço o acesso de leitura ao escopo do segredo

Você criou um escopo de segredo e armazenou o segredo do cliente da entidade de serviço nesse escopo. Agora você fornecerá à entidade de serviço o acesso para ler o segredo no escopo do segredo.

Abra um terminal e use a CLI do Databricks para executar o seguinte comando:

databricks secrets put-acl <scope-name> <application-id> READ

Substitua <scope-name> pelo nome do escopo do segredo do Azure Databricks que contém o segredo do cliente.
Substitua <application-id> com Application (client) ID para o registro de aplicativo do aplicativo Microsoft Entra ID.

Criar um trabalho no Azure Databricks e configurar o cluster para ler segredos no escopo do segredo

Agora você está pronto para criar um trabalho que pode ser executado como a nova entidade de serviço. Você usará um notebook criado na interface do usuário do Azure Databricks e adicionará a configuração para permitir que o cluster de trabalho recupere o segredo da entidade de serviço.

Acesse a página de aterrissagem do Azure Databricks e selecione Novo > Notebook. Dê um nome ao notebook e selecione SQL como a linguagem padrão.
Insira SELECT 1 na primeira célula do notebook. Esse é um comando simples que exibe apenas 1 se ele é bem-sucedido. Se você tiver fornecido à entidade de serviço o acesso a arquivos ou caminhos específicos no Azure Data Lake Storage Gen2, poderá ler esses caminhos.
Acesse Fluxos de trabalho e clique em Criar Trabalho. Dê um nome ao trabalho e à tarefa, clique em Selecionar Notebook e selecione o notebook recém-criado.
Clique em Editar ao lado das informações do cluster.
Na página Configurar Cluster, clique em Opções Avançadas.
Na guia Spark, insira a seguinte configuração do Spark:
```
fs.azure.account.auth.type.<storage-account>.dfs.core.windows.net OAuth
fs.azure.account.oauth.provider.type.<storage-account>.dfs.core.windows.net org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider
fs.azure.account.oauth2.client.id.<storage-account>.dfs.core.windows.net <application-id>
fs.azure.account.oauth2.client.secret.<storage-account>.dfs.core.windows.net {{secrets/<secret-scope-name>/<secret-name>}}
fs.azure.account.oauth2.client.endpoint.<storage-account>.dfs.core.windows.net https://login.microsoftonline.com/<directory-id>/oauth2/token
```
- Substitua <storage-account> pelo nome da conta de armazenamento que contém seus dados.
- Substitua <secret-scope-name> pelo nome do escopo do segredo do Azure Databricks que contém o segredo do cliente.
- Substitua <application-id> com Application (client) ID para o registro de aplicativo do aplicativo Microsoft Entra ID.
- Substitua <secret-name> pelo nome associado ao valor do segredo do cliente no escopo do segredo.
- Substitua <directory-id> com Directory (tenant) ID para o registro de aplicativo do aplicativo Microsoft Entra ID.

Transferir a propriedade do trabalho para a entidade de serviço

Um trabalho pode ter exatamente um proprietário. Portanto, você precisará transferir a propriedade do trabalho de você mesmo para a entidade de serviço. Para garantir que outros usuários possam gerenciar o trabalho, também é possível conceder permissões de acesso PODE GERENCIAR a um grupo. Neste exemplo, usamos a API de Permissões para definir essas permissões.

Abra um terminal e use a CLI do Databricks para executar o seguinte comando:

databricks permissions set jobs <job-id> --json '{
  "access_control_list": [
    {
      "service_principal_name": "<application-id>",
      "permission_level": "IS_OWNER"
    },
    {
      "group_name": "admins",
      "permission_level": "CAN_MANAGE"
    }
  ]
}'

Substitua <job-id> pelo identificador exclusivo do trabalho. Para localizar a ID do trabalho, clique em Fluxos de trabalho na barra lateral e clique no nome do trabalho. A ID do trabalho está no painel lateral Detalhes do trabalho.
Substitua <application-id> com Application (client) ID para o registro de aplicativo do aplicativo Microsoft Entra ID.

O trabalho também precisará ter permissões de leitura no notebook. Use a CLI do Databricks para executar o seguinte comando para conceder as permissões necessárias:

databricks permissions set notebooks <notebook-id> --json '{
  "access_control_list": [
    {
      "service_principal_name": "<application-id>",
      "permission_level": "CAN_READ"
    }
  ]
}'

Substitua <notebook-id> pela ID do notebook associado ao trabalho. Para encontrar a ID, acesse o notebook no workspace do Azure Databricks e procure a ID numérica após notebook/ na URL do notebook.
Substitua <application-id> com Application (client) ID para o registro de aplicativo do aplicativo Microsoft Entra ID.

Testar o trabalho

Você executa trabalhos com uma entidade de serviço da mesma forma que executa trabalhos como um usuário, seja por meio da interface do usuário, da API ou da CLI. Para testar o trabalho usando a interface do usuário do Azure Databricks:

Acesse Fluxos de Trabalho na interface do usuário do Azure Databricks e selecione o trabalho.
Clique em Executar Agora.

Você verá o status Êxito para o trabalho se tudo der certo. Selecione o trabalho na interface do usuário para verificar a saída:

Saída do trabalho

Saiba mais

Para saber mais sobre como criar e executar trabalhos, consulte Criar e executar trabalhos do Azure Databricks.

Compartilhar via