Esta página foi traduzida pela API Cloud Translation.

Usar o controle de acesso à fonte de dados

Esta página descreve como aplicar o controle de acesso à fonte de dados para apps de pesquisa no Vertex AI Agent Builder.

O controle de acesso às suas fontes de dados no Vertex AI Agent Builder limita os dados que os usuários podem acessar nos resultados do app de pesquisa. O Google usa seu provedor de identidade para identificar o usuário final que realiza uma pesquisa e determinar se ele tem acesso aos documentos retornados como resultados.

Por exemplo, digamos que os funcionários da sua empresa pesquisem documentos do Confluence usando seu app de pesquisa. No entanto, você precisa garantir que eles não possam acessar conteúdos pelo app. Se você tiver configurado um pool de força de trabalho no Google Cloud para o provedor de identidade da sua organização, também poderá especificar esse pool de força de trabalho no Vertex AI Agent Builder. Agora, se um funcionário usar seu app, ele vai receber resultados de pesquisa apenas para documentos a que a conta dele já tem acesso no Confluence.

Sobre o controle de acesso à fonte de dados

Ativar o controle de acesso é um procedimento único.

O controle de acesso está disponível para o Cloud Storage, o BigQuery, o Google Drive e todas as fontes de dados de terceiros.

Para ativar o controle de acesso à fonte de dados no Vertex AI Agent Builder, é necessário configurar o provedor de identidade da sua organização no Google Cloud. Os seguintes frameworks de autenticação são compatíveis:

Identidade do Google: se você usa a Identidade do Google, todas as identidades e grupos de usuários estão presentes e são gerenciados pelo Google Cloud. Para mais informações sobre o Google Identity, consulte a documentação do Google Identity.
Federação de provedor de identidade de terceiros: se você usa um provedor de identidade externo, como o Okta ou o Azure AD, é necessário configurar a federação de identidade de colaboradores no Google Cloud antes de ativar o controle de acesso à fonte de dados para o Vertex AI Agent Builder.

Se você usar conectores de terceiros, o atributo google.subject precisará ser mapeado para o campo de endereço de e-mail no provedor de identidade externo. Confira abaixo exemplos de mapeamentos de atributos google.subject e google.groups para provedores de identidade usados com frequência:
- Azure AD com protocolo OIDC
```
google.subject=assertion.email
google.groups=assertion.groups
```
- Azure AD com protocolo SAML
```
google.subject=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]
google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups']
```
- Okta com protocolo OIDC
```
google.subject=assertion.email
google.groups=assertion.groups
```
- Okta com protocolo SAML
```
google.subject=assertion.subject
google.groups=assertion.attributes['groups']
```

Limitações

O controle de acesso tem as seguintes limitações:

São permitidos 250 leitores por documento. Cada principal conta como um leitor, em que um principal pode ser um grupo ou um usuário individual.
É possível selecionar um provedor de identidade por local com suporte da Vertex AI para Pesquisa.
O controle de acesso é aceito apenas para identidades e grupos definidos explicitamente no provedor de identidade. Identidades ou grupos definidos nativamente em apps de terceiros não são aceitos.
Para definir uma fonte de dados como controlada por acesso, selecione essa configuração durante a criação do repositório de dados. Não é possível ativar ou desativar essa configuração para um repositório de dados existente.
A guia Dados > Documentos no console não mostra dados de fontes de dados controladas por acesso, porque esses dados só podem ser mostrados para os usuários que têm acesso de leitura.
Para conferir uma prévia dos resultados da interface de apps de pesquisa que usam o controle de acesso de terceiros, faça login no console federado ou use o app da Web. Consulte Prévia de resultados para apps com acesso controlado.

Antes de começar

Neste procedimento, presumimos que você tenha configurado um provedor de identidade no seu projeto do Google Cloud.

Identidade do Google: se você usa a Identidade do Google, prossiga para o procedimento de Conexão com o provedor de identidade.
Provedor de identidade de terceiros: verifique se você configurou um pool de identidade de colaboradores para o provedor de identidade de terceiros. Verifique se você especificou mapeamentos de atributos de assunto e grupo ao configurar o pool de força de trabalho. Para informações sobre mapeamentos de atributos, consulte Mapeamentos de atributos na documentação do IAM. Para mais informações sobre os pools de identidade da força de trabalho, consulte Gerenciar provedores de pools de identidade da força de trabalho na documentação do IAM.

Conectar ao provedor de identidade

Para especificar um provedor de identidade para o Vertex AI Agent Builder e ativar o controle de acesso à fonte de dados, siga estas etapas:

No Console do Google Cloud, acesse a página Criador de agentes.

Agent Builder.
Acesse a página Configurações > Autenticação.
Clique em Adicionar provedor de identidade para o local que você quer atualizar.
Selecione seu provedor de identidade na caixa de diálogo Adicionar provedor de identidade. Se você selecionar um provedor de identidade de terceiros, selecione também o pool de força de trabalho aplicável às suas fontes de dados.
Clique em Salvar alterações.

Configurar uma fonte de dados com controle de acesso

Para aplicar o controle de acesso a uma fonte de dados, siga as etapas abaixo, dependendo do tipo de fonte de dados que você está configurando:

Fontes de dados de terceiros: nenhuma configuração extra é necessária ao criar seu app. Pule para Prévia de resultados para apps com controle de acesso de terceiros.
Google Drive: não é necessário fazer nenhuma configuração extra ao criar o app.
Dados não estruturados do Cloud Storage
Dados estruturados do Cloud Storage
Dados não estruturados do BigQuery
Dados estruturados do BigQuery

Dados não estruturados do Cloud Storage

Ao configurar um repositório de dados não estruturados do Cloud Storage, você também precisa fazer upload de metadados de ACL e definir o repositório como acesso controlado:

Ao preparar seus dados, inclua informações de ACL nos metadados usando o campo acl_info. Exemplo:

{
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "content": {
     "mimeType": "<application/pdf or text/html>",
     "uri": "gs://<your-gcs-bucket>/directory/filename.pdf"
   },
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

Para mais informações sobre dados não estruturados com metadados, consulte a seção "Dados não estruturados" em Preparar dados para ingestão.

Ao seguir as etapas de criação de repositório de dados em Criar um repositório de dados de pesquisa, é possível ativar o controle de acesso fazendo o seguinte no console ou usando a API:
- Console: ao criar um repositório de dados, selecione Este repositório de dados contém informações de controle de acesso durante a criação.
- API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.
Ao seguir as etapas de importação de dados em Criar uma loja de dados de pesquisa, faça o seguinte:
- Faça upload dos metadados com informações de ACL do mesmo bucket dos seus dados não estruturados.
- Se estiver usando a API, defina GcsSource.dataSchema como document.

Dados estruturados do Cloud Storage

Ao configurar um repositório de dados estruturados do Cloud Storage, você também precisa fazer upload de metadados de ACL e definir o repositório como acesso controlado:

Ao preparar seus dados, inclua informações de ACL nos metadados usando o campo acl_info. Exemplo:

{
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

Ao seguir as etapas de criação de repositório de dados em Criar um repositório de dados de pesquisa, é possível ativar o controle de acesso fazendo o seguinte no console ou usando a API:
- Console: ao criar um repositório de dados, selecione Este repositório de dados contém informações de controle de acesso durante a criação.
- API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.
Ao seguir as etapas de importação de dados em Criar uma loja de dados de pesquisa, faça o seguinte:
- Faça upload dos metadados com informações de ACL do mesmo bucket dos seus dados não estruturados.
- Se estiver usando a API, defina GcsSource.dataSchema como document.

Dados não estruturados do BigQuery

Ao configurar um repositório de dados não estruturados do BigQuery, é necessário definir o repositório como acesso controlado e fornecer metadados de ACL usando um esquema predefinido para a Pesquisa da Vertex AI:

Ao preparar os dados, especifique o esquema a seguir. Não use um esquema personalizado.

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "content",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mimeType",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

Inclua os metadados da ACL como uma coluna na tabela do BigQuery.
Ao seguir as etapas em Criar uma loja de dados de pesquisa, ative o controle de acesso no console ou usando a API:
- Console: ao criar um repositório de dados, selecione Este repositório de dados contém informações de controle de acesso durante a criação.
- API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.
Ao seguir as etapas de importação de dados em Criar um repositório de dados de pesquisa, se você estiver usando a API, defina BigQuerySource.dataSchema como document.

Dados estruturados do BigQuery

Ao configurar um repositório de dados estruturados do BigQuery, é necessário definir o repositório como acesso controlado e fornecer metadados de ACL usando um esquema predefinido para a Pesquisa da Vertex AI:

Ao preparar os dados, especifique o esquema a seguir. Não use um esquema personalizado.

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

Inclua os metadados da ACL como uma coluna na tabela do BigQuery.
Ao seguir as etapas em Criar uma loja de dados de pesquisa, ative o controle de acesso no console ou usando a API:
- Console: ao criar um repositório de dados, selecione Este repositório de dados contém informações de controle de acesso durante a criação.
- API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.
Ao seguir as etapas de importação de dados em Criar um repositório de dados de pesquisa, faça o seguinte:
- Se você estiver usando o console, ao especificar o tipo de dados que está enviando, selecione JSONL para dados estruturados com metadados.
- Se estiver usando a API, defina BigQuerySource.dataSchema como document.

Visualizar resultados de apps com controle de acesso de terceiros

Para visualizar os resultados no console para apps com controle de acesso de terceiros, é necessário fazer login com as credenciais da sua organização.

Há duas maneiras de visualizar os resultados da UI:

Console da Federação de identidade da força de trabalho. Abra o console da federação de identidade de colaboradores e faça login com suas credenciais de terceiros. Consulte Visualizar resultados no console da federação de identidade de colaboradores.
App da Web: ative e faça login em um app da Web dedicado fornecido pela Vertex AI para Pesquisa. Consulte Ativar o app da Web.

Visualizar resultados no console da Federação de identidade da força de trabalho

Siga estas etapas para usar o console da Federação de identidade da força de trabalho e conferir os resultados:

No Console do Google Cloud, acesse a página Criador de agentes.

Agent Builder.
Clique no nome do app de pesquisa cujos resultados você quer visualizar.
Acesse a página Visualizar.
Clique em Visualizar com identidade federada para acessar o console da federação de identidade da força de trabalho.
Insira as credenciais do provedor do pool de força de trabalho e da organização.
Confira os resultados do app na página Visualização que aparece.

Para mais informações sobre a visualização dos resultados da pesquisa, consulte Receber resultados da pesquisa.

Para mais informações sobre o console da Federação de identidade de colaboradores, consulte Sobre o console (federado).

Conceder permissões de pesquisa aos usuários

Para permitir que os usuários pesquisem dados controlados por acesso usando seu app, conceda acesso aos usuários no seu domínio ou pool de força de trabalho. O Google recomenda que você conceda um papel personalizado do IAM ao seu grupo de usuários.

Identidade do Google: se você usa a Identidade do Google, o Google recomenda criar um Grupo do Google que inclua todos os funcionários que precisam pesquisar. Se você for administrador do Google Workspace, poderá incluir todos os usuários de uma organização em um grupo do Google seguindo as etapas em Adicionar todos os usuários da sua organização a um grupo.
Provedor de identidade de terceiros: se você usa um provedor de identidade externo, como o Okta ou o Azure AD, adicione todos no pool de força de trabalho a um grupo único.

O Google recomenda que você crie um papel do IAM personalizado para conceder ao grupo de usuários, usando as seguintes permissões:

discoveryengine.answers.get
discoveryengine.servingConfigs.answer
discoveryengine.servingConfigs.search
discoveryengine.sessions.get

Para mais informações sobre as permissões dos recursos do Vertex AI Agent Builder que usam o Identity and Access Management (IAM), consulte Controle de acesso com o IAM.

Para mais informações sobre papéis personalizados, consulte Papéis personalizados na documentação do IAM.

Se você quiser implantar um widget de pesquisa para um app controlado por acesso, siga estas etapas:

Conceda o papel de leitor do Discovery Engine aos usuários no seu domínio ou pool de força de trabalho que precisam fazer chamadas de API de pesquisa.
Gere tokens de autorização para transmitir ao widget:
- Para o Google Identity: gere tokens de acesso do OAuth 2.0.
- Para a federação de identidade da força de trabalho: siga as etapas em Receber tokens de curta duração para a federação de identidade da força de trabalho para conseguir seu token.
Siga as etapas em Adicionar um widget com um token de autorização para transmitir o token ao widget.

Ativar o app da Web

O app da Web é um site dedicado gerado pela Vertex AI para Pesquisa, em que você e qualquer outro usuário com credenciais de login podem usar o app de pesquisa.

Para fornecer o app de pesquisa aos usuários sem precisar integrar o widget de pesquisa ou a API de pesquisa no seu próprio aplicativo, forneça o URL do app da Web aos usuários.

Siga estas etapas para ativar o app da Web:

No Console do Google Cloud, acesse a página Criador de agentes.

Agent Builder.
Clique no nome do app de pesquisa para criar um app da Web.

O app de pesquisa precisa estar associado a pelo menos uma origem de dados com controle de acesso. Para mais informações, consulte Configurar uma fonte de dados com controle de acesso.
Acesse a guia Integration > UI.
Clique em Ativar o app da Web.
Se você estiver usando a federação de identidade da força de trabalho, selecione um provedor de pool de força de trabalho.
Clique no link para o app da Web.
Insira as credenciais do provedor do pool de força de trabalho e da organização.
Visualize os resultados do app.
Para configurar os resultados do app da Web, acesse Configurar resultados para o widget de pesquisa. Todas as configurações do widget também se aplicam ao app da Web.
Opcional: para fornecer o app de pesquisa aos usuários por meio desse app da Web dedicado, copie o URL e envie-o para os usuários que têm credenciais de login. Eles podem adicionar o URL do app da Web aos favoritos e acessar o app de pesquisa.

Para mais informações sobre como receber resultados da pesquisa, consulte Receber resultados da pesquisa.