Pular para o conteúdo principal
Última atualização em

Tutorial: definir o escopo do acesso de um agente de AI com RBAC

Use role-based access control (RBAC) para limitar o acesso de um agente de AI aos dados e aos recursos de que ele precisa para uma tarefa específica. Forneça ao agente um token OAuth com escopo para uma função. As solicitações feitas com esse token usam as permissões da função em vez das permissões mais amplas do usuário autenticador ou do Service Principal do Databricks.

Cenário​

Um agente de suporte de IA precisa de resumos e status de tickets, mas não de detalhes de contato do cliente que contenham informações de identificação pessoal (PII). O seu service principal do Databricks de autenticação tem acesso mais amplo e pode ler ambos os datasets.

Neste exemplo, o esquema support.tickets contém resumos de tickets e status sem PII de cliente. Os detalhes de contato do cliente são armazenados separadamente em support.customers.contact_details.

Você cria role-support-agent, dá a ele acesso de leitura a support.tickets e concede ao Service Principal do Databricks a permissão Assume nele. Com um tokens com escopo para essa função, o agente pode ler tickets de suporte, mas não consegue acessar detalhes de contato do cliente.

A função pode herdar privilégios de dados de grupos pai, e concessões de catálogo ou esquema podem ser aplicadas a todas as tabelas abaixo deles. Para este exemplo, verifique se essas concessões não fornecem à função acesso à tabela de contato do cliente. Consulte Herança de privilégios. Alterar concessões compartilhadas afeta outros usuários e funções; portanto, use um workspace de teste em vez de remover o acesso de outros usuários.

Este tutorial é destinado a agentes personalizados, hospedados em conta própria ou de terceiros que aceitam um access token OAuth fornecido por você. Para agentes implantados no Databricks Apps, use a autorização de aplicativo ou usuário integrada. Consulte Autenticação para agentes.

Pré-requisitos​

  • Um workspace habilitado para o Unity Catalog com RBAC habilitado. Consulte Habilitar RBAC.
  • Permissões de administrador de account ou administrador de Workspace para criar a função, conceder a permissão Assume e atribuí-la ao Workspace. Consulte Quem pode gerenciar grupos?.
  • Propriedade do, ou MANAGE no, catálogo support.
  • Permissões de administrador do Workspace ou "Pode gerenciar" no SQL warehouse usado no exemplo.
  • Tabelas existentes support.tickets.open_cases e support.customers.contact_details. Use dados de teste fictícios e substitua pelos seus próprios nomes por toda parte, se necessário.
  • Uma Service Principal do Databricks atribuída ao Workspace, com acesso ao Databricks SQL, pode usar no warehouse e permissão para consultar ambas as tabelas. Ele precisa de um segredo de OAuth que permita o escopo sql para autenticação máquina a máquina (M2M). Consulte O passo 1: Criar um segredo de OAuth.
  • curl em um ambiente confiável onde você pode solicitar e testar tokens.
  • Um leitor de auditoria com acesso a system.access.audit para verificar a atividade do agente na função. Consulte Verificar atribuição de auditoria.

o passo 1: criar a role​

Para este tutorial, crie um grupo de account vazio para servir como a funçã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 Grupos , clique em Adicionar grupo .
  4. Digite role-support-agent. Não adicionar membros.
  5. Clique em Confirmar .
  6. Atribua o grupo ao workspace com acesso ao Databricks SQL . Consulte Atribuir um grupo a um workspace.

O direito de acesso ao Databricks SQL concede acesso aos recursos do Databricks SQL, incluindo painéis, queries e SQL Warehouse. O exemplo usa queries SQL. Se o seu agente também precisar de recursos principais do workspace, como notebooks, jobs, modelos ou pipelines, conceda acesso ao Workspace. Consulte Access entitlements (Direitos de acesso). Você configura privilégios de dados e permissões de warehouse no Passo 2.

Neste exemplo, você concede a permissão Assume separadamente em vez de adicionar o service principal do Databricks como um membro. A associação também adiciona as permissões do grupo à própria identidade do service principal do Databricks.

O passo 2: Conceder à função acesso a tickets de suporte​

Como proprietário do catálogo ou um usuário com MANAGE em support, execução:

SQL
GRANT USE CATALOG ON CATALOG support TO `role-support-agent`;
GRANT USE SCHEMA, SELECT ON SCHEMA support.tickets TO `role-support-agent`;

Como administrador do workspace ou usuário com Can manage (Pode gerenciar) no warehouse, conceda à função acesso ao warehouse:

  1. Na barra lateral do workspace, clique em SQL Warehouses .
  2. Clique no menu kebab Ícone de menu Kebab. ao lado do warehouse e depois clique em Permissões .
  3. Adicione role-support-agent com Pode usar .

A concessão SELECT em nível de schema se aplica a todas as tabelas e views atuais e futuras em support.tickets. Ela não concede acesso a support.customers ou outros schemas. Para restringir a role a uma tabela, conceda SELECT nessa tabela. Consulte Gerenciar privilégios no Unity Catalog.

O passo 3: Conceder permissão para assumir a role​

Conceda ao service principal do Databricks a permissão Assume usando qualquer método:

  1. Como um administrador account, abra o console account e clique em Gerenciamento de usuários .
  2. Na tab Grupos , clique em role-support-agent.
  3. Clique na tab Permissões e clique em Conceder acesso .
  4. Pesquise e selecione o Service Principal do Databricks, selecione Assumir e clique em Salvar .

O passo 4: Solicitar um token com escopo de função​

No seu ambiente de solicitação de token confiável, defina estas variáveis de ambiente:

  • DATABRICKS_HOST: a URL do workspace, incluindo https:// e sem uma barra final.
  • CLIENT_ID e CLIENT_SECRET: o ID do aplicativo da Service Principal do Databricks e o segredo do OAuth.
  • ROLE_GROUP_ID: o ID numérico de role-support-agent. Um administrador account pode encontrá-lo no final do URL do grupo no console da account. Os administradores de account, administradores de Workspace e gerentes de grupo também podem recuperar o id do grupo usando a API de grupos de account.
  • DATABRICKS_SQL_WAREHOUSE_ID: o ID do warehouse concedido no Passo 2. Ele segue /sql/1.0/warehouses/ no caminho HTTP do warehouse. Consulte Obter detalhes de conexão para um recurso de compute do Databricks.

Solicite um token de nível de workspace com o parâmetro assume_group e o escopo OAuth sql. O escopo limita o token a APIs SQL. Os privilégios de dados da função determinam quais tabelas ela pode query. Consulte Segredos OAuth com escopo.

Para solicitar o token, execução:

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/oidc/v1/token" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=sql' \
  --data-urlencode "assume_group=$ROLE_GROUP_ID"

Defina DATABRICKS_TOKEN para o valor access_token da resposta. Use o valor expires_in para determinar quando solicitar uma substituição. Solicitações de tokens no nível da account não oferecem suporte a assume_group. Consulte Assumir uma função.

O passo 5: Verificar o acesso do token​

Execução estas verificações no ambiente confiável antes de fornecer o token ao agente.

Primeiro, obtenha uma linha de base com um token para a própria identidade do service principal do Databricks. Repita a solicitação no passo 4 sem o parâmetro assume_group e defina temporariamente DATABRICKS_TOKEN como esse token. Faça a execução das duas query neste passo e verifique se elas foram bem-sucedidas. Em seguida, defina DATABRICKS_TOKEN de volta para o tokens com escopo de função e repita as verificações.

Ler tíquetes de suporte​

execução esta solicitação com os tokens de escopo de função:

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT * FROM support.tickets.open_cases LIMIT 10\",
    \"wait_timeout\": \"50s\"
  }"

A query é bem-sucedida porque a função pode ler support.tickets. Verifique se status.state da resposta é SUCCEEDED. Se for PENDING ou RUNNING, use statement_id retornado para recuperar o resultado com o mesmo token:

Bash
curl --request GET \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements/<statement-id>" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN"

Consulte API de execução de instrução: execução SQL em warehouse para status da instrução e tratamento de resultados.

Verifique se o acesso a PII do cliente está negado​

Usando o mesmo token de escopo de função e warehouse, execução:

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT 1 FROM support.customers.contact_details LIMIT 1\",
    \"wait_timeout\": \"50s\"
  }"

Se a instrução ainda estiver sendo executada, recupere o resultado conforme descrito na seção anterior. A query falha com um erro de permissão em status.error, embora tenha êxito com o próprio token do Databricks service principal. Uma resposta de sucesso HTTP por si só não significa que a query foi bem-sucedida. Uma tabela ausente, um token expirado ou um erro de warehouse não estabelece que os privilégios de dados da role estão configurados corretamente.

Verificar atribuição de auditoria​

Use um leitor de auditoria com o acesso descrito em Verify audit attribution (Verificar atribuição de auditoria). Inspecione os eventos de query de teste em system.access.audit: identity_metadata.run_as identifica a função autorizadora, run_as_display_name contém role-support-agent e run_by identifica o Databricks service principal que iniciou a solicitação. Os dados de auditoria são atualizados ao longo do dia, portanto, um evento recente pode não aparecer imediatamente. Consulte Identity metadata reference (Referência de metadados de identidade).

O passo 6: Configurar o agente​

Configure o cliente Databricks do agente com a URL do workspace e o token escotado por função verificado. Forneça apenas esse token ao agente, não o segredo OAuth da Service Principal do Databricks nem seu token não escopado. O tokens com escopo de função limita as solicitações feitas com esse token. Ele não remove as permissões do Service Principal do Databricks em outras sessões.

Para um agente que usa o Databricks SDK para Python, defina DATABRICKS_HOST e DATABRICKS_TOKEN no ambiente do agente e, em seguida, inicialize o cliente:

Python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

O SDK lê o token do ambiente usando autenticação unificada. Fornecer um access token não dá ao SDK as credenciais de que ele precisa para solicitar um novo token. Para um agente de longa execução, providencie um componente confiável para solicitar e fornecer um token de escopo de role de substituição antes que o token expire.

Opcional: use a identidade de um desenvolvedor​

Para testes locais com autenticação de usuário para máquina (U2M), conceda a um desenvolvedor participante a permissão Assume no role-support-agent, como no o passo 3. O desenvolvedor instala a CLI do Databricks conforme descrito em Instalar ou atualizar a CLI do Databricks e, em seguida, autentica-se usando seu próprio login e um perfil separado:

Bash
databricks auth login --host <workspace-url> --profile support-agent

O desenvolvedor seleciona role-support-agent em Autorizar como.. no navegador e clica em Continuar , então recupera o token para esse perfil:

Bash
databricks auth token --profile support-agent

O desenvolvedor usa o access_token retornado como DATABRICKS_TOKEN para as verificações de query com escopo de função no Passo 5. Os eventos de auditoria dessas solicitações identificam o desenvolvedor como run_by. O token retornado pela CLI do Databricks expira. O desenvolvedor recupera um novo token quando necessário. Consulte API (tokens de acesso OAuth).

Limpar​

Para um teste temporário, remova a configuração de tokens do agente e revogue a concessão da permissão Assume criada para o teste quando terminar. Antes de excluir a role, verifique se ela possui ativos ou se é usada por outros workloads.

Os passos seguintes​

Nesta página