Gerenciar entidades de serviço

Este artigo explica como criar e gerenciar entidades de serviço para seus workspaces e conta do Azure Databricks.

Para obter uma visão geral do modelo de identidade do Azure Databricks, confira Identidades do Azure Databricks.

Para gerenciar o acesso das entidades de serviço, confira Autenticação e controle de acesso.

O que é uma entidade de serviço?

Uma entidade de serviço é uma identidade criada no Azure Databricks para uso com ferramentas automatizadas, trabalhos e aplicativos. As entidades de serviço concedem as ferramentas automatizadas e scripts Acesso somente à API a recursos do Azure Databricks, fornecendo maior segurança do que o uso de usuários ou grupos.

Você pode conceder e restringir o acesso de uma entidade de serviço aos recursos da mesa forma que um usuário do Azure Databricks. Por exemplo, você pode fazer o seguinte:

• Atribuir funções de administrador da conta e do workspace à entidade de serviço.
• Conceder a uma entidade de serviço acesso aos dados, no nível da conta usando o Catálogo do Unity ou no nível do workspace.
• Adicionar uma entidade de serviço a um grupo no nível da conta e do workspace, incluindo o grupo admins de workspaces.

Você também pode conceder aos usuários, entidades de serviço e grupos do Azure Databricks permissões para usar uma entidade de serviço. Isso permite que os usuários executem trabalhos como a entidade de serviço, em vez de sua identidade. Isso evita que os trabalhos falhem se um usuário sair da sua organização ou se um grupo for modificado.

Ao contrário de um usuário do Azure Databricks, uma entidade de serviço é uma identidade somente API; ela não pode ser usada para acessar a interface do usuário do Azure Databricks.

O Databricks recomenda que você habilite seus workspaces para federação de identidade. A federação de identidade permite que você configure as entidades de serviço no console da conta e, em seguida, atribua a elas acesso a workspaces específicos. Isso simplifica a administração e a governança de dados do Azure Databricks.

Entidades de serviço do Databricks e do Microsoft Entra ID

As entidades de serviço podem ser entidades de serviço gerenciadas do Azure Databricks ou entidades de serviço gerenciadas do Microsoft Entra ID.

As entidades de serviço gerenciadas do Azure Databricks podem se autenticar no Azure Databricks usando a autenticação do Databricks OAuth e tokens de acesso pessoal. As entidades de serviço gerenciadas do Microsoft Entra ID podem se autenticar no Azure Databricks usando a autenticação OAuth do Databricks e os tokens de ID do Microsoft Entra. Para mais informações sobre a autenticação para entidades de serviço, confira Gerenciar tokens de uma entidade 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 automação do Azure Databricks e use as entidades de serviço gerenciadas do Microsoft Entra ID nos casos em que você deve autenticar com o Azure Databricks e outros recursos do Azure ao mesmo tempo.

Para criar uma entidade de serviço gerenciada do Azure Databricks, ignore esta seção e continue lendo com Quem pode gerenciar e usar entidades de serviço?.

Para usar as entidades de serviço gerenciadas do Microsoft Entra ID no Azure Databricks, um usuário administrador deve criar um aplicativo de ID do Microsoft Entra no Azure. Para criar uma entidade de serviço gerenciada do Microsoft Entra ID, siga estas instruções:

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.

Quem pode gerenciar e usar os entidades de serviço?

Para gerenciar as entidades de serviço no Azure Databricks, você deve ter um dos seguintes: a função de administrador da conta, a função de administrador do espaço de trabalho ou a função de gerente ou usuário em uma entidade de serviço.

• Os administradores da conta podem adicionar entidades de serviço à conta e atribuir-lhes funções de administrador. Eles também podem atribuir entidades de serviço a espaços de trabalho, desde que esses espaços de trabalho usem federação de identidade.
• Os administradores do espaço de trabalho podem adicionar entidades de serviço a um espaço de trabalho do Azure Databricks, atribuir a elas a função de administrador do espaço de trabalho e gerenciar o acesso a objetos e funcionalidades no espaço de trabalho, como a capacidade de criar clusters ou acessar ambientes baseados em personas específicas.
• Os Gerentes da Entidade de Serviço podem gerenciar funções em uma entidade de serviço. O criador de uma entidade de serviço torna-se o gerente da entidade de serviço. Os administradores da conta são gerentes de entidades de serviço em todas as entidades de serviço de uma conta.

• Os Usuários da Entidade de Serviço podem executar trabalhos como a entidade de serviço. O trabalho é executado usando a identidade da entidade de serviço, em vez da identidade do proprietário do trabalho. Para obter mais informações, consulte Gerenciar identidades, permissões e privilégios para trabalhos do Databricks.

Para obter informações sobre como conceder as funções de gerente da entidade de serviço e de usuário, consulte Funções para gerenciar entidades de serviço.

Gerenciar entidades de serviço na sua conta

Os administradores de contas podem adicionar entidades de serviço à sua conta do Azure Databricks usando o console da conta.

Adicionar entidades de serviço à conta usando o console da conta

As entidades de serviço podem ser criadas no Azure Databricks ou vinculadas a partir de uma entidade de serviço do Microsoft Entra ID existente. Consulte principais serviços do Databricks e Microsoft Entra ID.

1. Como administrador de conta, faça logon no console da conta.
2. Na barra lateral, clique em Gerenciamento de usuários .
3. Na guia Entidades de serviço, clique em Adicionar entidade de serviço.
4. Em Gerenciamento, escolha Gerenciada pelo Databricks ou Gerenciada pelo Microsoft Entra ID.
5. Se você escolheu Gerenciada pelo Microsoft Entra ID, na opção ID do aplicativo do Microsoft Entra, insira a ID do aplicativo (cliente) da entidade de serviço.
6. Insira um nome para a entidade de serviço.
7. Clique em Adicionar.

Atribuir as funções de administrador de conta a uma entidade de serviço

1. Como administrador de conta, faça logon no console da conta.
2. Na barra lateral, clique em Gerenciamento de usuários .
3. Na guia Entidades de serviço, localize e clique no nome de usuário.
4. Na guia Funções, ative a opção Administrador da conta ou Administrador do marketplace.

Atribuir uma entidade de serviço a um workspace usando o console da conta

Para adicionar usuários a um espaço de trabalho usando o console da conta, o espaço de trabalho deve estar habilitado para federação de identidade. Os administradores do espaço de trabalho também podem atribuir entidades de serviço aos espaços de trabalho usando a página de configurações do administrador do espaço de trabalho. Para obter detalhes, confira Adicionar uma entidade de serviço a um espaço de trabalho usando as configurações de administrador do espaço de trabalho.

1. Como administrador de conta, faça logon no console da conta.
2. Na barra lateral, clique em Workspaces.
3. Clique no nome do seu workspace.
4. Na guia Permissões, clique em Adicionar permissões.
5. Pesquise e selecione a entidade de serviço, atribua o nível de permissão (usuário do workspace ou Administrador) e clique em Salvar.

Remover uma entidade de serviço de um workspace usando o console da conta

Para remover entidades de serviço de um workspace usando o console da conta, o workspace deve ser habilitado para federação de identidade. Quando uma entidade de serviço é removida de um workspace, ela perde o acesso ao workspace; no entanto, as permissões são mantidas na entidade de serviço. Se a entidade de serviço for adicionada de volta ao workspace, ela recuperará suas permissões anteriores.

1. Como administrador da conta, faça logon no console da conta
2. Na barra lateral, clique em Workspaces.
3. Clique no nome do seu workspace.
4. Na guia Permissões, localize a entidade de serviço.
5. Clique no menu kebab no canto direito da linha da entidade de serviço e selecione Remover.
6. No diálogo de confirmação, clique em Remover.

Desativar uma entidade de serviço em sua conta do Azure Databricks

Os administradores da conta podem desativar entidades de serviço de uma conta do Azure Databricks. Uma entidade de serviço desativada não pode se autenticar na conta ou workspaces do Azure Databricks. No entanto, todas as permissões da entidade de serviço e objetos de workspace permanecem inalterados. Quando uma entidade de serviço é desativada, o seguinte é verdadeiro:

• A entidade de serviço não pode se autenticar na conta ou em qualquer um de seus workspaces com qualquer método.
• Aplicativos ou scripts que usam os tokens gerados pela entidade de serviço não podem mais acessar a API do Databricks. Os tokens permanecem, mas não podem ser utilizados para autenticação enquanto uma entidade de serviço estiver desativada.
• Os clusters de propriedade da entidade de serviço permanecem em execução.
• Os trabalhos agendados criados pela entidade de serviço falham, a menos que sejam atribuídos a um novo proprietário.

Quando uma entidade de serviço é reativada, ela pode fazer logon no Azure Databricks com as mesmas permissões. O Databricks recomenda desativar as entidades de serviço da conta em vez de removê-las, porque remover uma entidade de serviço é uma ação destrutiva. O status de uma entidade de serviço desativada é rotulado como Inativo no console da conta. Você também pode desativar uma entidade de serviço de um espaço de trabalho específico. Consulte Desativar uma entidade de serviço no seu espaço de trabalho do Azure Databricks.

Não é possível desativar uma entidade de serviço usando o console da conta. Em vez disso, use a API de Entidades de Serviço de Conta.

Por exemplo:

curl --netrc -X PATCH \
https://${DATABRICKS_HOST}/api/2.1/accounts/{account_id}/scim/v2/ServicePrincipals/{id} \
--header 'Content-type: application/scim+json' \
--data @update-sp.json \
| jq .

update-sp.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": [
        {
          "value": "false"
        }
      ]
    }
  ]
}

Remova as entidades de serviço da sua conta do Azure Databricks

Os administradores da conta podem excluir entidades de serviço de uma conta do Azure Databricks. Os administradores do workspace não podem. Quando você exclui uma entidade de serviço da conta, essa entidade também é removida dos workspaces.

Quando uma entidade de serviço do Microsoft Entra ID é removida de uma conta, ela perde o acesso à conta e aos workspaces associadas; no entanto, as permissões são mantidas na entidade de serviço. Se a entidade de serviço for adicionada de volta à conta, ela recuperará suas permissões anteriores.

Para remover uma entidade de serviço usando o console da conta, faça o seguinte:

1. Como administrador da conta, faça logon no console da conta.
2. Na barra lateral, clique em Gerenciamento de usuários .
3. Na guia Entidades de serviço, localize e clique no nome de usuário.
4. Na guia Informações da Entidade, clique no menu kebab no canto superior direito e selecione Excluir.
5. Na caixa de diálogo de confirmação, clique em Confirmar exclusão.

Gerenciar entidades de serviço em seu espaço de trabalho

Os administradores do espaço de trabalho podem gerenciar as entidades de serviço em seus espaços de trabalho usando a página de configurações do administrador do espaço de trabalho.

Adicionar uma entidade de serviço a um workspace usando as configurações de administração do workspace

As entidades de serviço podem ser criadas no Azure Databricks ou vinculadas a partir de uma entidade de serviço do Microsoft Entra ID existente. Consulte principais serviços do Databricks e Microsoft Entra ID.

1. Como administrador do workspace, faça logon no workspace do Azure Databricks.

2. Clique no seu nome de usuário na barra superior do workspace do Azure Databricks e selecione Configurações.

3. Clique na guia Identidade e acesso.

4. Ao lado de Entidades de serviço, clique em Gerenciar.

5. Clique em Adicionar entidade de serviço.

6. Selecione uma entidade de serviço existente para atribuir ao workspace ou clique em Adicionar nova para criar uma nova.

   Para adicionar uma nova entidade de serviço, selecione Gerenciada pelo Databricks ou Gerenciada pelo Microsoft Entra ID. Se você escolheu Gerenciada pelo Microsoft Entra ID, insira o ID do aplicativo (cliente) da entidade de serviço e defina um nome de exibição.

7. Clique em Adicionar.

Atribua a função de administrador do espaço de trabalho a uma entidade de serviço usando a página de configurações do administrador do espaço de trabalho

1. Como administrador do workspace, faça logon no workspace do Azure Databricks.
2. Clique no seu nome de usuário na barra superior do workspace do Azure Databricks e selecione Configurações.
3. Clique na guia Identidade e acesso.
4. Ao lado de Grupos, clique em Gerenciar.
5. Selecione o admins grupo de sistema.
6. Clique em Adicionar membros.
7. Selecione a entidade de serviço e clique em Confirmar.

Para remover a função de administrador do workspace de uma entidade de serviço, remova a entidade de serviço do grupo de administradores.

Desativar uma entidade de serviço no seu Workspace do Azure Databricks

Os administradores do espaço de trabalho podem desativar as entidades de serviço em um Workspace do Azure Databricks. Uma entidade de serviço desativada não pode acessar o espaço de trabalho a partir das APIs do Azure Databricks, mas todas as permissões da entidade de serviço e os objetos do espaço de trabalho permanecem inalterados. Quando uma entidade de serviço for desativada:

• A entidade de serviço não pode se autenticar nos espaços de trabalho a partir de nenhum método.
• O status da entidade de serviço é mostrado como Inativo na página de configuração do administrador do workspace.
• Aplicativos ou scripts que usam os tokens gerados pela entidade de serviço não podem mais acessar a API do Databricks. Os tokens permanecem, mas não podem ser utilizados para autenticação enquanto uma entidade de serviço estiver desativada.
• Os clusters de propriedade da entidade de serviço permanecem em execução.
• Os trabalhos agendados criados pela entidade de serviço devem ser atribuídos a um novo proprietário para evitar que eles falhem.

Quando uma entidade de serviço é reativada, ela pode se autenticar no workspace com as mesmas permissões. O Databricks recomenda desativar as entidades de serviço em vez de removê-las, porque remover uma entidade de serviço é uma ação destrutiva.

1. Como administrador do workspace, faça logon no workspace do Azure Databricks.
2. Clique no seu nome de usuário na barra superior do workspace do Azure Databricks e selecione Configurações.
3. Clique na guia Identidade e acesso.
4. Ao lado das entidades de serviço, clique em Gerenciar.
5. Selecione a entidade de serviço que você deseja desativar.
6. Em Status, desmarque Ativa.

Para definir uma entidade de serviço como ativa, execute as mesmas etapas, mas marque a caixa de seleção.

Remover uma entidade de serviço de um espaço de trabalho usando a página de configurações de administração do espaço de trabalho

A remoção de uma entidade de serviço de um espaço de trabalho não remove a entidade de serviço da conta. Para remover uma entidade de serviço da sua conta, confira Remover entidades de serviço da sua conta do Azure Databricks.

Quando uma entidade de serviço é removida de um workspace, ela perde o acesso ao workspace; no entanto, as permissões são mantidas na entidade de serviço. Se a entidade de serviço for adicionada de volta a um workspace, ela recuperará suas permissões anteriores.

1. Como administrador do workspace, faça logon no workspace do Azure Databricks.
2. Clique no seu nome de usuário na barra superior do workspace do Azure Databricks e selecione Configurações.
3. Clique na guia Identidade e acesso.
4. Ao lado das entidades de serviço, clique em Gerenciar.
5. Selecione a entidade de serviço.
6. No canto superior direito, clique em Excluir.
7. Clique em Excluir para confirmar.

Gerenciar entidades de serviço usando a API

Os administradores de contas e espaços de trabalho podem gerenciar entidades de serviço na conta e nos espaços de trabalho do Azure Databricks usando as APIs do Databricks. Para gerenciar funções em uma entidade de serviço usando a API, confira Gerenciar funções de entidade de serviço usando a CLI do Databricks.

Gerenciar as entidades de serviço na conta usando a API

Os administradores podem adicionar e gerenciar as entidades de serviço na conta do Azure Databricks usando a API de Entidades de Serviço para Contas. Administradores de conta e administradores de workspace invocam a API usando uma URL de ponto de extremidade diferente:

• Os administradores da conta usam {account-domain}/api/2.1/accounts/{account_id}/scim/v2/.
• Os administradores do workspace usam {workspace-domain}/api/2.0/account/scim/v2/.

Para obter detalhes, consulte a API das Entidades de Serviço da Conta.

Gerenciar entidades de serviço no espaço de trabalho usando a API

Os administradores de contas e espaços de trabalho podem usar a API de Atribuição do Espaço de Trabalho para atribuir entidades de serviço a espaços de trabalho habilitados para federação de identidade. A API de Atribuição de Workspace tem suporte por meio da conta e dos workspaces do Azure Databricks.

• Os administradores da conta usam {account-domain}/api/2.0/accounts/{account_id}/workspaces/{workspace_id}/permissionassignments.
• Os administradores do workspace usam {workspace-domain}/api/2.0/preview/permissionassignments/principals/{principal_id}.

Consulte API de Atribuição do Espaço de Trabalho.

Se o seu espaço de trabalho não estiver habilitado para a federação por identidade, um administrador do espaço de trabalho poderá usar as APIs no nível do espaço de trabalho para atribuir entidades de serviço aos seus espaços de trabalho. Consulte API de Entidades de Serviço do Espaço de Trabalho.

Gerenciar tokens para uma entidade de serviço

As entidades de serviço podem se autenticar em APIs no Azure Databricks usando tokens OAuth do Azure Databricks ou tokens de acesso pessoal do Azure Databricks, da seguinte maneira:

• Os tokens OAuth do Azure Databricks podem ser usados para autenticar nas APIs no nível do workspace e da conta do Azure Databricks.
  • Os tokens OAuth do Azure Databricks, criados no nível de conta do Azure Databricks, podem ser usados para autenticar nas APIs no nível do workspace e da conta do Azure Databricks.
  • Os tokens OAuth do Azure Databricks, criados no nível de workspace do Azure Databricks, podem ser usados para autenticar somenta nas APIs no nível do workspace do Azure Databricks.
• Os tokens de acesso pessoal do Azure Databricks podem ser usados para autenticar somente nas APIs no nível do workspace do Azure Databricks.

As entidades de serviço também podem se autenticar em APIs no Azure Databricks usando os tokens do Microsoft Entra ID.

Gerenciar a autenticação OAuth do Databricks para uma entidade de serviço

Para autenticar nas APIs REST do Databricks no nível da conta e no workspace, os administradores de conta podem usar tokens OAuth do Azure Databricks para entidades de serviço. Você pode solicitar um token OAuth usando a ID do cliente e um segredo do cliente para a entidade de serviço. Para obter mais informações, consulte Autenticar o acesso ao Azure Databricks com uma entidade de serviço usando OAuth (OAuth M2M).

Gerenciar tokens de acesso pessoal para uma entidade de serviço

Para autenticar uma entidade de serviço nas APIs no nível do workspace apenas no Azure Databricks, uma entidade de serviço pode criar tokens de acesso pessoal do Databricks para si mesma, da seguinte maneira:

Este procedimento pressupõe que você esteja usando a autenticação OAuth máquina-a-máquina (M2M) ou a autenticação de entidade de serviço do Microsoft Entra ID para configurar a CLI do Databricks para autenticar a entidade de serviço para gerar tokens de acesso pessoal do Azure Databricks para si mesmo. Consulte Autenticação OAuth máquina-a-máquina (M2M) ou Autenticação da entidade de serviço do Microsoft Entra ID.

1. Use a CLI do Databricks para executar o seguinte comando, que gera outro token de acesso para a entidade de serviço.

   Execute o comando a seguir:

   databricks tokens create --comment <comment> --lifetime-seconds <lifetime-seconds> -p <profile-name>
   

   • --comment: substitua <comment> por um comentário significativo sobre a finalidade do token de acesso. Se a opção --comment não for especificada, nenhum comentário será gerado.
   • --lifetime-seconds: substitua <lifetime-seconds> pelo número de segundos durante os quais o token de acesso será válido. Por exemplo, 1 dia corresponde a 86.400 segundos. Se a opção --lifetime-seconds não for especificada, o token de acesso estará definido para nunca expirar (não recomendado).
   • --profile-name: substitua <profile-name> pelo nome de um perfil de configuração do Azure Databricks que contenha informações de autenticação para a entidade de segurança e o espaço de trabalho de destino. Se a opção -p não for especificada, a CLI do Databricks tentará encontrar e usar um perfil de configuração chamado DEFAULT.

2. Na resposta, copieo valor de token_value, que é o token de acesso da entidade de serviço.

   Lembre-se de salvar o token copiado em um local seguro. Não compartilhe seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente aquele mesmo token. Em vez disso, será necessário repetir esse procedimento para criar um novo token.

   Se você não conseguir criar ou usar tokens em seu workspace, isso pode ocorrer porque o administrador do workspace desabilitou tokens ou não deu permissão para criar ou usar tokens. Veja o administrador do workspace ou o seguinte:

   • Habilitar ou desabilitar a autenticação de token de acesso pessoal para o workspace
   • Permissões do token de acesso pessoal

Gerenciar a autenticação do Microsoft Entra ID para uma entidade de serviço

Somente as entidades de serviço gerenciadas do Microsoft Entra ID podem se autenticar em APIs usando tokens de ID do Microsoft Entra. Para criar um token de acesso do Microsoft Entra ID, consulte Obter tokens do Microsoft Entra ID para entidades de serviço.

O token de acesso do Microsoft Entra ID pode ser usado para chamar a API de Tokens para criar um token de acesso pessoal do Databricks para a entidade de serviço.