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 Databricks, consulte identidades 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.

Você também pode conceder permissões de usuários, entidades de serviço e grupos do Databricks para usar uma entidade de serviço. Isso permite que os usuários executem Job como a entidade de serviço, em vez de como sua identidade. Isso evita que Job falhe se um usuário deixar sua organização ou 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.

A Databricks recomenda que você habilite seu espaço de trabalho para federação de identidades. A federação de identidades permite configurar entidades de serviço no console account e, em seguida, atribuir-lhes acesso a um espaço de trabalho específico. Isso simplifica a administração do Databricks e a governança de dados.

Importante

Se sua account foi criada depois de 8 de novembro de 2023, a federação de identidade será habilitada em todos os novos workspace por default e não poderá ser desativada.

Quem pode gerir e utilizar a entidade de serviço?

Para entidades de serviço gerenciado em Databricks, você deve ter um dos seguintes: 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.
os administradoresworkspace podem adicionar entidade de serviço a um workspace Databricks, atribuir a eles a função de administrador workspace e gerenciar o acesso a objetos e funcionalidades no workspace, como a capacidade de criar clusters ou acessar ambientes baseados em persona especificados.
Os gerentes principais 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. administradores account são gerentes de entidades de serviço em todas as entidades de serviço em uma 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 por default. Peça a um administrador account para conceder a você a função de gerente de entidade de serviço.

entidade de serviço Os usuários podem executar o Job como a entidade de serviço. A Job execução usando a identidade da entidade de serviço, em vez da identidade do proprietário da Job. Para obter mais informações, consulte a execução a Job as a service principal.

entidade de serviço Os usuários que são administradores do espaço de trabalho também podem criar 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 funções de usuário e gerente de entidade de serviço, consulte Funções para gerenciar entidades de serviço.

gerenciar entidade de serviço em sua conta

os administradores account podem adicionar entidade de serviço à sua account Databricks 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 tab Funções, ative o administrador account ou o Marketplace administrador

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 console de conta, o workspace deve ser habilitado para federação de identidade. os administradores workspace também podem atribuir entidade de serviço ao workspace usando a página de configurações do administrador workspace . Para obter detalhes, consulte Adicionar uma entidade de serviço a um workspace usando as configurações de administração 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 seu 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 entidade de serviço de um espaço de trabalho usando o console account , o espaço de trabalho deve estar habilitado para 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 posteriormente adicionada de volta ao workspace, ela recuperará as permissões anteriores.

Como administrador da conta, logs in no console da conta
Na barra lateral, clique em Espaços de trabalho.
Clique no nome do seu 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.

Desative uma entidade de serviço em sua conta do Databricks

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

A entidade de serviço não pode autenticar a account ou qualquer um de seus workspace de qualquer método.
Aplicativos ou scripts que usam os tokens gerados pela entidade de serviço não podem mais acessar a API Databricks. Os tokens permanecem, mas não podem ser usados para autenticação enquanto uma entidade de serviço está desativada.
Os clusters pertencentes à entidade de serviço permanecem em execução.
Job agendado criado pela entidade de serviço falha, a menos que seja atribuído a um novo proprietário.

Quando uma entidade de serviço é reativada, ela pode fazer login no Databricks com as mesmas permissões. A Databricks recomenda desativar a entidade de serviço da account em vez de removê-la porque remover uma entidade de serviço é uma ação destrutiva. Consulte Remover entidade de serviço da sua accountdo Databricks. Quando você desativa uma entidade de serviço da account, essa entidade de serviço também é desativada do seu espaço de trabalho federado de identidade.

Você não pode desativar um usuário usando o console account . Em vez disso, use a API da account entidade de serviço. Consulte Desativar uma entidade de serviço usando a API.

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 você remove uma entidade de serviço da account, essa entidade de serviço também é removida de seu workspace, independentemente de a federação de identidade ter sido habilitada ou não. Recomendamos que você evite excluir entidades de serviço no nível account , a menos que queira que elas percam o acesso a todos os workspace da account. Esteja ciente das seguintes consequências da exclusão da entidade de serviço:

Aplicativos ou scripts que usam os tokens gerados pela entidade de serviço não podem mais acessar APIs do Databricks
Os trabalhos pertencentes à entidade de serviço falham
clusters de propriedade da entidade de serviço param
query 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 falhas no compartilhamento

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 em seu espaço de trabalho

os administradores workspace podem gerenciar a entidade de serviço em seu workspace usando a página de configurações do administrador 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 na Identidade e acesso tab.
Ao lado de entidade de serviço, clique em gerenciar.
Clique em Adicionar entidade de serviço.
Selecione uma entidade de serviço existente para atribuir ao workspace ou clique em Adicionar novo para criar uma nova.
Clique em Adicionar.

Observação

Se sua workspace não estiver habilitada para federação de identidade, você não poderá atribuir uma entidade de serviço de account existente à sua workspace.

Atribua a função de administrador do espaço de trabalho a uma entidade de serviço usando a página de 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 na Identidade e acesso tab.
Ao lado de Grupos, 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.

Desative uma entidade de serviço em seu espaço de trabalho Databricks

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

A entidade de serviço não pode autenticar no workspace 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 Databricks. Os tokens permanecem, mas não podem ser usados para autenticação enquanto uma entidade de serviço está desativada.
Os clusters pertencentes à entidade de serviço permanecem em execução.
Job agendado criado pela entidade de serviço deve ser atribuído a um novo proprietário para evitar falhas.

Quando uma entidade de serviço é reativada, ela pode autenticar-se no workspace com as mesmas permissões. A Databricks recomenda desativar os principais de serviço em vez de removê-los porque 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 na Identidade e acesso tab.
Ao lado de entidade de serviço, clique em gerenciar.
Selecione a entidade de serviço que você deseja desativar.
Em Status, desmarque Ativo.

Para definir uma entidade de serviço como ativa, execute os mesmos passos, mas marque a caixa de seleção.

Remova 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 workspace não remove a entidade de serviço da account. Para remover uma entidade de serviço de sua account, consulte remover entidades de serviço de sua accountDatabricks.

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 posteriormente adicionada novamente 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 na 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 a API

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

gerenciar entidade de serviço na conta usando a API

Os administradores podem adicionar e gerenciar a entidade de serviço na account do Databricks usando a API da entidade de serviço account . administradores account e administradores workspace invocam a API usando um URL de endpoint diferente:

Administradores de conta usam {account-domain}/api/2.0/accounts/{account_id}/scim/v2/.
Os administradores do workspace usam {workspace-domain}/api/2.0/account/scim/v2/.

Para obter detalhes, consulte a API da conta entidade de serviço.

Desativar uma entidade de serviço usando a API

Os administradores de conta podem alterar o status de uma entidade de serviço para falso para desativar a entidade de serviço usando a API de entidades de serviço de conta.

Por exemplo:

curl --netrc -X PATCH \
https://${DATABRICKS_HOST}/api/2.0/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"
        }
      ]
    }
  ]
}

O status de uma entidade de serviço desativada é o rótulo Inativo no console account . Quando você desativa uma entidade de serviço da account, essa entidade de serviço também é desativada de seu workspace.

gerenciar entidade de serviço no espaço de trabalho usando a API

os administradores account e workspace podem usar a API de atribuição workspace para atribuir entidade de serviço ao workspace habilitado para federação de identidade. A API de atribuição workspace tem suporte por meio da account e workspace do Databricks.

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 workspace poderá usar as APIs no nível workspacepara atribuir entidade de serviço ao seu workspace. Consulte API da entidade de serviço do espaço de trabalho.

gerenciar tokens para uma entidade de serviço

A entidade de serviço pode se autenticar nas APIs da Databricks usando os tokens OAuth da Databricks ou o token de acesso pessoal da Databricks, como segue:

Os tokens OAuth da Databricks podem ser usados para autenticação nas APIs de nível accounte workspaceda Databricks.
- Os tokens OAuth da Databricks criados no nível da Databricks account podem ser usados para autenticar as APIs de nível da Databricks accounte workspace.
- Os tokens OAuth da Databricks que são criados no nível da Databricks workspace podem ser usados para autenticar somente as APIs de nível da Databricks workspace.
O token de acesso pessoal da Databricks pode ser usado para autenticar apenas as APIs de nível da Databricks workspace.

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

Para autenticar APIs REST do Databricks no nível accounte do workspace , os administradores account podem usar tokens OAuth do Databricks para entidade de serviço. Você pode solicitar tokens OAuth usando o ID do cliente e um segredo do cliente para a entidade de serviço. Para obter mais informações, consulte Autenticação máquina a máquina (M2M) OAuth.

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

Para autenticar uma entidade de serviço em APIs de nível workspacesomente na Databricks, um administrador da workspace que seja um usuário da entidade de serviço pode criar um token de acesso pessoal da Databricks em nome da entidade de serviço, como segue:

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.

Observação

O senhor não pode usar a interface de usuário da Databricks para gerar o token de acesso pessoal da Databricks para a entidade de serviço da Databricks. Esse processo usa o Databricks CLI versão 0.205 ou superior para gerar um access token para uma entidade de serviço do Databricks. Se o senhor ainda não tiver a CLI da Databricks instalada, consulte Instalar ou atualizar a CLI da Databricks.

Configure a autenticação para a CLI do Databricks, se o senhor ainda não tiver feito isso. Uma maneira de configurar isso é usar primeiro a autenticação pessoal do Databricks access token para o usuário do Databricks workspace. Consulte a autenticação pessoal do Databricks access token .
Obtenha o ID do aplicativo para a entidade de serviço Databricks, se o senhor ainda não o tiver disponível:
1. Se o console de administração do seu workspace ainda não estiver aberto, clique no seu nome de usuário na barra superior do workspacee clique em Settings (Configurações).
2. Em workspace admin, clique em Identity and access (Identidade e acesso).
3. Ao lado de entidade de serviço, clique em gerenciar.
4. Clique no nome da entidade de serviço Databricks para abrir sua página de configurações. Se o nome não estiver visível, use Filtrar entidade de serviço para encontrá-lo.
5. Em Configurations (Configurações ) tab, observe o valor do Application Id (ID do aplicativo ).
Use a CLI da Databricks para executar o seguinte comando, que gera o access token para a entidade de serviço da Databricks.

No comando a seguir, substitua esses espaços reservados:
- Substitua <application-id> pelo ID do aplicativo da entidade de serviço Databricks.
- Substitua <lifetime-seconds> pelo número de segundos pelo qual o access token é válido. Por exemplo, 1 dia equivale a 86400 segundos.
- Opcionalmente, substitua <comment> por qualquer comentário significativo sobre a finalidade do access token. Se a opção --comment não for especificada, nenhum comentário será gerado.
- Opcionalmente, substitua <profile-name> pelo nome de um perfil de configuração do Databricks que contenha informações de autenticação para o usuário e o destino do Databricks workspace. Por exemplo, consulte a autenticação pessoal da Databricks em access token . Se a opção -p não for especificada, a CLI do Databricks tentará localizar e usar um perfil de configuração denominado DEFAULT.
```
databricks token-management create-obo-token <application-id> --lifetime-seconds <lifetime-seconds> --comment <comment> -p <profile-name>
```
Na resposta, copie o valor de token_value, que é o access token da entidade de serviço do Databricks.

É importante que você salve 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á gerar de novo exatamente o mesmo token. Em vez disso, você deverá repetir esse procedimento para criar outro token.

Se não for possível criar ou usar tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou os tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do workspace ou o seguinte:
- Ativar ou desativar a autenticação pessoal access token para o workspace
- Pessoal access token permissões

Uma entidade de serviço pode, então, usar seu próprio access token pessoal da Databricks para criar um token de acesso pessoal adicional da Databricks para si mesma, como segue:

Observação

O senhor não pode usar a interface de usuário da Databricks para gerar o token de acesso pessoal da Databricks para a entidade de serviço da Databricks. Esse processo usa o Databricks CLI versão 0.205 ou superior para gerar um access token para uma entidade de serviço do Databricks. Se o senhor ainda não tiver a CLI da Databricks instalada, consulte Instalar ou atualizar a CLI da Databricks.

Este procedimento pressupõe que o senhor já tenha gerado o primeiro Databricks pessoal access token para a entidade de serviço Databricks. O senhor usa esse access token para configurar a CLI da Databricks para autenticar a entidade de serviço da Databricks, de modo que ela possa gerar um token de acesso adicional para si mesma. Consulte a autenticação pessoal do Databricks access token .

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

No comando a seguir, substitua esses espaços reservados:
- Opcionalmente, substitua <comment> por qualquer comentário significativo sobre a finalidade do access token. Se a opção --comment não for especificada, nenhum comentário será gerado.
- Opcionalmente, substitua <lifetime-seconds> pelo número de segundos para os quais o access token é válido. Por exemplo, 1 dia equivale a 86400 segundos. Se a opção --lifetime-seconds não for especificada, o site access token será definido para nunca expirar (não recomendado).
- Opcionalmente, substitua <profile-name> pelo nome de um perfil de configuração do Databricks que contenha informações de autenticação para a entidade de serviço do Databricks e o destino workspace. Se a opção -p não for especificada, a CLI do Databricks tentará localizar e usar um perfil de configuração denominado DEFAULT.
```
databricks tokens create --comment <comment> --lifetime-seconds <lifetime-seconds> -p <profile-name>
```
Na resposta, copie o valor de token_value, que é o access token para a entidade de serviço Databricks.

É importante que você salve 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á gerar de novo exatamente o mesmo token. Em vez disso, você deverá repetir esse procedimento para criar outro token.

Se não for possível criar ou usar tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou os tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do workspace ou o seguinte:
- Ativar ou desativar a autenticação pessoal access token para o workspace
- Pessoal access token permissões