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.

Observação

A entidade de serviço está gerenciando em Databricks. Eles não se integram à conta de serviço do Google cloud .

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

Se o seu account foi criado após 6 de março de 2024, a federação de identidade é ativada em todos os novos espaços de trabalho pelo default e não pode ser desativada.

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.

• 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 execução a Job as a entidade de serviço.

  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

1. Como administrador da conta, faça login 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. Insira um nome para a entidade de serviço.

5. Clique em Adicionar.

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

1. Como administrador da conta, faça login 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 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 .

1. Como administrador da conta, faça login no console da conta.

2. Na barra lateral, clique em Espaços de trabalho.

3. Clique no nome do 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 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.

1. Como account administrador do , log in acesse o account console em

2. Na barra lateral, clique em Espaços de trabalho.

3. Clique no nome do workspace.

4. Na guia Permissões, localize a entidade de serviço.

5. Clique no menu kebab na extremidade direita da linha da entidade de serviço e selecione Remover.

6. 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. Consulte Remover entidade de serviço de seu site Databricks account . Quando o senhor desativa uma entidade de serviço do site account, essa entidade de serviço também é desativada do espaço de trabalho federado de identidade.

Não é possível desativar um usuário usando o console account. Em vez disso, use o endereço account entidade de serviço API. 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 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:

1. Como administrador da conta, faça login 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 principais, clique no botão menu kebab no canto superior direito e selecione Excluir.

5. 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

1. Como administrador do espaço de trabalho, faça logon no espaço de trabalho Databricks.

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

3. Clique em Identity and access (Identidade e acesso ) tab.

4. Ao lado de entidade de serviço, clique em gerenciar.

5. Clique em Add entidade de serviço.

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

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

1. Como administrador do espaço de trabalho, faça logon no espaço de trabalho Databricks.

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

3. Clique em Identity and access (Identidade e acesso ) tab.

4. Ao lado de Groups, clique em gerenciar.

5. Selecione o grupo de sistemas admins.

6. Clique em Adicionar membros.

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

1. Como administrador do espaço de trabalho, faça logon no espaço de trabalho Databricks.

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

3. Clique em Identity and access (Identidade e acesso ) tab.

4. Ao lado de entidade de serviço, clique em gerenciar.

5. Selecione a entidade de serviço que deseja desativar.

6. 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.

1. Como administrador do espaço de trabalho, faça logon no espaço de trabalho Databricks.

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

3. Clique em Identity and access (Identidade e acesso ) tab.

4. Ao lado de entidade 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 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.0/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.

Desativar uma entidade de serviço usando a API

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

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 Inactive (Inativo ) no console account. Quando o senhor desativa uma entidade de serviço do site account, essa entidade de serviço também é desativada de seu espaço de trabalho.

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 OAuth machine-to-machine (M2M) authentication.

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

Para autenticar uma entidade de serviço no workspace-level APIs somente no Databricks, um administrador do workspace que seja um usuário da entidade de serviço pode criar um Databricks pessoal access tokens em nome da entidade de serviço, da seguinte forma:

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

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

1. 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 Databricks personal access token para o usuário Databricks workspace . Consulte Databricks autenticação pessoal access token .

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

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

   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 Databricks que contenha informações de autenticação para o usuário Databricks e o alvo workspace. Por exemplo, consulte Databricks personal access token authentication. 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>
   

4. Na resposta, copie o valor de token_value, que é o access token para sua Databricks entidade de serviço.

   É 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 o 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 Databricks personal access token para criar um Databricks personal access tokens adicional para si mesma, como segue:

Observação

Não é possível usar a interface de usuário Databricks para gerar Databricks pessoal access tokens para Databricks entidade de serviço. Esse processo usa Databricks CLI versão 0.205 ou superior para gerar um access token para uma Databricks entidade de serviço. 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 personal access token para a Databricks entidade de serviço. O senhor usa esse access token para configurar o Databricks CLI para autenticar a Databricks entidade de serviço para que ela possa gerar access tokens adicionais para si mesma. Consulte Databricks autenticação pessoal access token .

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

   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 Databricks que contenha informações de autenticação para a Databricks entidade de serviço 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>
   

2. Na resposta, copie o valor de token_value, que é o access token para a Databricks entidade de serviço.

   É 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 o 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