Gerenciar entidades de serviço

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

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

Para gerenciar o acesso à entidade de serviço, consulte Autenticação e controle de acesso.

O que é um principal de serviço?

Uma entidade de serviço é uma identidade que você cria no Databricks para uso com ferramentas, trabalhos e aplicativos automáticos. As entidades de serviço oferecem ferramentas automáticas e scripts de acesso somente por API aos recursos do 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 mesma forma que faz com um usuário do Databricks. Por exemplo, você pode fazer o seguinte:

Conceda a uma entidade de serviço as funções de administrador de conta e workspace
Conceda a uma entidade de serviço acesso aos dados, seja no nível da conta usando o Unity Catalog ou no nível do workspace.
Adicione uma entidade de serviço a um grupo no nível da conta e do workspace, incluindo o grupo admins do workspace.

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

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

Databricks recomenda que o senhor habilite seu espaço de trabalho para a federação de identidade. A federação de identidade permite que o senhor configure a entidade de serviço no console account e, em seguida, atribua a ela acesso a um espaço de trabalho específico. Isso simplifica a administração e a governança de dados do Databricks.

Importante

Databricks começou a habilitar o novo espaço de trabalho para federação de identidade e Unity Catalog automaticamente em 8 de novembro de 2023, com uma implementação gradual em toda a conta. Se o seu workspace estiver habilitado para a federação de identidade por default, ele não poderá ser desabilitado. Para obter mais informações, consulte Habilitação automática do Unity Catalog site .

Quem pode gerenciar e usar a entidade de serviço?

Para gerenciar a entidade de serviço em Databricks, o senhor deve ter uma das seguintes opções: a função de administrador account, a função de administrador workspace ou a função de gerente ou usuário em uma entidade de serviço.

os administradores account podem adicionar entidade de serviço à account e atribuir-lhes funções administrativas. Eles também podem atribuir entidade de serviço a workspace, desde que esses workspace usem federação de identidade.
workspace Os administradores podem adicionar entidades de serviço a um Databricks workspace, atribuir-lhes a função de administrador do workspace e gerenciar o acesso a objetos e funcionalidades no workspace, como a capacidade de criar clusters ou acessar ambientes baseados em personas específicas.
entidade de serviço Os gerentes 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. account Os administradores são gerentes de entidades de serviço em todas as entidades de serviço em um site account.

Observação

Se uma entidade de serviço tiver sido criada antes de 13 de junho de 2023, o criador da entidade de serviço não terá a função de gerente da entidade de serviço pelo site default. Solicite a um administrador do account que conceda ao senhor a função de gerente de entidade de serviço.

Os usuários com a função de gerente da entidade de serviço não herdam a função de usuário da entidade de serviço. Se quiser usar a entidade de serviço para executar o trabalho, o senhor precisa atribuir-se explicitamente a função de usuário de entidade de serviço, mesmo depois de criar a entidade de serviço.

entidade de serviço Os usuários podem executar o Job como a entidade de serviço. A execução do trabalho 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 Databricks Jobs.

entidade de serviço Os usuários que são administradores do workspace também podem criar o tokens em nome da entidade de serviço.

Observação

Quando a configuração RestrictWorkspaceAdmins em um workspace é definida como ALLOW ALL, os administradores do workspace podem criar um access token pessoal em nome de qualquer entidade de serviço em seu workspace. Consulte Restringir administradores do espaço de trabalho.

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 a entidade de serviço.

gerenciar entidade de serviço no seu account

account Os administradores podem adicionar entidades de serviço ao seu Databricks account usando o console account.

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

Como administrador da conta, faça login no console da conta.
Na barra lateral, clique em Gerenciamento de usuários.
Na guia Entidades de serviço, clique em Adicionar entidade de serviço.
Insira um nome para a entidade de serviço.
Clique em Adicionar.

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

Como administrador da conta, faça login no console da conta.
Na barra lateral, clique em Gerenciamento de usuários.
Na guia Entidades de serviço, localize e clique no nome de usuário.
Na aba Funções, habilite Administrador da conta ou Administrador do Marketplace.

Atribua uma entidade de serviço a um espaço de trabalho usando o console de conta

Para adicionar usuários a um workspace usando o consoleaccount , o workspace deve estar habilitado para a federação de identidade. workspace Os administradores também podem atribuir uma entidade de serviço ao espaço de trabalho usando a página de configurações de administração workspace. Para obter detalhes, consulte Adicionar uma entidade de serviço a um workspace usando as configurações de administração do workspace .

Como administrador da conta, faça login no console da conta.
Na barra lateral, clique em Espaços de trabalho.
Clique no nome do workspace.
Na guia Permissões, clique em Adicionar permissões.
Pesquise e selecione a entidade de serviço, atribua o nível de permissão ( usuário ou administradordo espaço de trabalho) e clique em Salvar.

Remova uma entidade de serviço de um espaço de trabalho usando o console da conta

Para remover a entidade de serviço de um workspace usando o console account, o workspace deve estar habilitado para a federação de identidade. Quando uma entidade de serviço é removida de um workspace, a entidade de serviço não pode mais acessar o workspace, porém as permissões são mantidas na entidade de serviço. Se a entidade de serviço for adicionada novamente ao site workspace, ela recuperará suas permissões anteriores.

Como administrador da conta, faça login no console da conta
Na barra lateral, clique em Espaços de trabalho.
Clique no nome do workspace.
Na guia Permissões, localize a entidade de serviço.
Clique no menu kebab na extremidade direita da linha da entidade de serviço e selecione Remover.
Na caixa de diálogo de confirmação, clique em Remover.

Desativar uma entidade de serviço em sua conta da Databricks

account Os administradores podem desativar a entidade de serviço em um site Databricks account. Uma entidade de serviço desativada não pode se autenticar no site Databricks account ou no espaço de trabalho. No entanto, todas as permissões da entidade de serviço e os objetos do site workspace permanecem inalterados. Quando uma entidade de serviço é desativada, o seguinte é verdadeiro:

A entidade de serviço não pode se autenticar no site account ou em qualquer um de seus espaços de trabalho a partir de qualquer método.
Os aplicativos ou scripts que usam os tokens gerados pela entidade de serviço não podem mais acessar a API da Databricks. Os tokens permanecem, mas não podem ser usados para autenticação enquanto uma entidade de serviço estiver desativada.
clusters de propriedade da entidade de serviço permanecem em funcionamento.
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 login no Databricks com as mesmas permissões. Databricks recomenda desativar a entidade de serviço do site account em vez de removê-la, pois remover uma entidade de serviço é uma ação destrutiva. O status de uma entidade de serviço desativada é o rótulo Inactive (Inativo ) no console account. O senhor também pode desativar uma entidade de serviço de um site específico workspace. Consulte Desativar uma entidade de serviço em seu espaço de trabalho do Databricks.

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

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"
        }
      ]
    }
  ]
}

Remover entidades de serviço da sua conta do Databricks

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

Importante

Quando o senhor remove uma entidade de serviço do site account, essa entidade de serviço também é removida do espaço de trabalho, independentemente de a federação de identidade ter sido ativada ou não. Recomendamos que o senhor não exclua a account-level entidade de serviço, a menos que queira que ela perca o acesso a todo o espaço de trabalho na account. Esteja ciente das seguintes consequências da exclusão da entidade de serviço:

Os aplicativos ou scripts que usam os tokens gerados pela entidade de serviço não podem mais acessar as APIs da Databricks
Os empregos pertencentes à entidade de serviço falham
clusters de propriedade da entidade de serviço stop
As consultas ou painéis criados pela entidade de serviço e compartilhados usando a credencial de execução como proprietário devem ser atribuídos a um novo proprietário para evitar que o compartilhamento falhe.

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

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

gerenciar entidade de serviço no seu workspace

workspace Os administradores podem gerenciar a entidade de serviço em seu espaço de trabalho usando a página de configurações de administração workspace.

Adicione uma entidade de serviço a um espaço de trabalho usando as configurações de administração do espaço de trabalho

Como administrador do espaço de trabalho, faça logon no espaço de trabalho Databricks.
Clique no seu nome de usuário na barra superior do site Databricks workspace e selecione Settings (Configurações).
Clique em Identity and access (Identidade e acesso ) tab.
Ao lado de entidade de serviço, clique em gerenciar.
Clique em Add entidade de serviço.
Selecione uma entidade de serviço existente para atribuir ao site workspace ou clique em Add new para criar uma nova.
Clique em Adicionar.

Observação

Se o seu workspace não estiver habilitado para a federação de identidade, o senhor não poderá atribuir a account entidade de serviço existente ao seu workspace.

Atribuir 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

Como administrador do espaço de trabalho, faça logon no espaço de trabalho Databricks.
Clique no seu nome de usuário na barra superior do site Databricks workspace e selecione Settings (Configurações).
Clique em Identity and access (Identidade e acesso ) tab.
Ao lado de Groups, clique em gerenciar.
Selecione o grupo de sistemas admins.
Clique em Adicionar membros.
Selecione a entidade de serviço e clique em Confirmar.

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

Desativar uma entidade de serviço em seu espaço de trabalho do Databricks

workspace Os administradores podem desativar a entidade de serviço em Databricks workspace. Uma entidade de serviço desativada não pode acessar o site workspace de Databricks APIs, porém todas as permissões da entidade de serviço e os objetos workspace permanecem inalterados. Quando uma entidade de serviço é desativada:

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

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

Como administrador do espaço de trabalho, faça logon no espaço de trabalho Databricks.
Clique no seu nome de usuário na barra superior do site Databricks workspace e selecione Settings (Configurações).
Clique em Identity and access (Identidade e acesso ) tab.
Ao lado de entidade de serviço, clique em gerenciar.
Selecione a entidade de serviço que deseja desativar.
Em Status, desmarque a opção Active.

Para definir uma entidade de serviço como ativa, execute os mesmos passos, 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 site workspace não remove a entidade de serviço do site account. Para remover uma entidade de serviço do site account, consulte Remover entidade de serviço do site Databricks account .

Quando uma entidade de serviço é removida de um workspace, a entidade de serviço não pode mais acessar o workspace, porém as permissões são mantidas na entidade de serviço. Se a entidade de serviço for adicionada posteriormente a um workspace, ela recuperará suas permissões anteriores.

Como administrador do espaço de trabalho, faça logon no espaço de trabalho Databricks.
Clique no seu nome de usuário na barra superior do site Databricks workspace e selecione Settings (Configurações).
Clique em Identity and access (Identidade e acesso ) tab.
Ao lado de entidade de serviço, clique em gerenciar.
Selecione a entidade de serviço.
No canto superior direito, clique em Excluir.
Clique em Excluir para confirmar.

gerenciar entidade de serviço usando o API

account Os administradores e os administradores do workspace podem gerenciar a entidade de serviço no Databricks account e no espaço de trabalho usando o Databricks APIs. Para gerenciar funções em uma entidade de serviço usando o API, consulte gerenciar funções de entidade de serviço usando o Databricks CLI .

gerenciar entidade de serviço no site account usando o API

Os administradores podem adicionar e gerenciar entidades de serviço no site Databricks account usando o site account entidade de serviço API. account e os administradores do workspace invocam o API usando um URL endpoint diferente:

Administradores de 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 o site account entidade de serviço API.

gerenciar entidade de serviço no site workspace usando o API

account e os administradores do workspace podem usar o workspace Assignment API para atribuir a entidade de serviço ao espaço de trabalho habilitado para a federação de identidade. O workspace Assignment API é suportado pelo Databricks account e pelo espaço de trabalho.

Administradores de 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 de workspace.

Se o seu workspace não estiver habilitado para federação de identidade, um administrador do workspace poderá usar o workspace-level APIs para atribuir entidade de serviço ao seu espaço de trabalho. Consulte workspace entidade de serviço API.

gerenciar tokens para uma entidade de serviço

A entidade de serviço pode se autenticar em APIs em Databricks usando Databricks OAuth tokens ou Databricks pessoal access tokens, como segue:

Databricks OAuth tokens pode ser usado para autenticar em Databricks account-level e workspace-level APIs.
- Databricks OAuth tokens que são criados no nível Databricks account podem ser usados para autenticar em Databricks account-level e workspace-level APIs.
- Databricks OAuth tokens que são criados no nível Databricks workspace podem ser usados para autenticar somente para Databricks workspace-level APIs.
Databricks O access tokens pessoal pode ser usado para autenticar apenas o Databricks workspace-level APIs.

gerenciar Databricks OAuth autenticação para uma entidade de serviço

Para se autenticar em account-level e workspace-level Databricks REST APIs, os administradores de account podem usar Databricks OAuth tokens para entidade de serviço. O senhor pode solicitar um OAuth tokens usando o ID do cliente e um segredo do cliente para a entidade de serviço. Para obter mais informações, consulte Autenticar o acesso a Databricks com uma entidade de serviço usando OAuth (OAuth M2M).

Veja também

Para obter detalhes sobre como trabalhar com a entidade de serviço como um desenvolvedor que trabalha com o Databricks CLI ou Databricks REST APIs, consulte Autenticar o acesso a Databricks com uma entidade de serviço usando OAuth (OAuth M2M).