Usar o controle de acesso da 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 no Confluence documentos usando seu aplicativo de pesquisa. No entanto, você precisa garantir que eles não possam visualizar conteúdo no app que elas não têm permissão para acessar. 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 aplicativo, ele receberá resultados da pesquisa apenas para documentos que seu já tem acesso no Confluence.

Sobre o controle de acesso da 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 o Google Identity, todas as identidades e usuários grupos são presentes e gerenciados pelo Google Cloud. Para mais informações sobre identidade do Google, consulte o artigo sobre identidade do Google na documentação do Google Cloud.

  • Federação de provedores de identidade de terceiros: se você usa uma conta externa como o Okta ou o Azure AD, configure a federação de identidade de colaboradores no Google Cloud antes de ativar o controle de acesso à fonte de dados no 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 alguns exemplos google.subject e google.groups mapeamentos de atributos 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 aplicativos de terceiros não têm suporte.
  • Para definir uma fonte de dados como controlada por acesso, selecione essa configuração durante a criação de repositório de dados. Não é possível ativar ou desativar essa configuração para um serviço repositório de dados.
  • Na guia Dados > A guia Documentos no console não mostra os dados de para fontes de dados com acesso controlado, porque esses dados só devem ser visíveis usuários com acesso de leitura.
  • Para visualizar os resultados da UI em apps de pesquisa que usam acesso de terceiros controle, faça login no console federado ou use o app da Web. Consulte Visualizar resultados de 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 o Google Identity, pode prosseguir para Procedimento de conexão com o provedor de identidade.
  • Provedor de identidade de terceiros: verifique se você configurou um pool de identidade da força de trabalho para o provedor de identidade de terceiros. Verifique se você tem mapeamentos de assunto e atributo de grupo especificados 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 pools de identidade de colaboradores, consulte Gerenciar pool de identidade de colaboradores provedores na documentação do IAM.

Conectar-se 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:

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

    Agent Builder.

  2. Acesse Configurações > Authentication.

  3. Clique em Adicionar provedor de identidade para o local que você quer atualizar.

  4. 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 que se aplica às suas fontes de dados.

  5. 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 das o tipo de fonte de dados que você está configurando:

Dados não estruturados do Cloud Storage

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

  1. Ao preparar seus dados, inclua as informações da ACL nos metadados usando o 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.

  2. Ao seguir as etapas para criar um repositório de dados em Criar um repositório de dados Store, é possível ativar o controle de acesso fazendo o 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.

  3. Ao seguir as etapas para importação de dados em Criar uma lista de dados de pesquisa store, faça o seguinte:

    • Faça upload dos metadados com as informações da ACL do mesmo bucket que 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:

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

  2. Ao seguir as etapas para criar um repositório de dados em Criar um repositório de dados Store, é possível ativar o controle de acesso fazendo o 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 do repositório de dados.
    • API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.

  3. 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 as informações da ACL do mesmo bucket que 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, é preciso definir o repositório de dados como controlado por acesso e fornecer metadados de ACL usando um esquema predefinido para a Vertex AI para Pesquisa:

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

  2. Inclua os metadados da ACL como uma coluna na tabela do BigQuery.

  3. Ao seguir as etapas em Criar dados de pesquisa Store, 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 do repositório de dados.
    • API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.

  4. 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, é preciso definir o repositório de dados como controlado por acesso e fornecer metadados de ACL usando um esquema predefinido para a Vertex AI para Pesquisa:

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

  2. Inclua os metadados da ACL como uma coluna na tabela do BigQuery.

  3. 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 do repositório de dados.
    • API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.

  4. Ao seguir as etapas de importação de dados em Criar um repositório de dados de pesquisa, faça o seguinte:

    • Se estiver usando o console, ao especificar o tipo de dados que você está fazendo upload, 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.

É possível visualizar os resultados da UI de duas maneiras:

Prévia dos resultados no console da federação de identidade de colaboradores

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

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

    Agent Builder.

  2. Clique no nome do app de pesquisa cujos resultados você quer visualizar.

  3. Acesse a página Visualizar.

  4. Clique em Visualizar com identidade federada para acessar o console da federação de identidade da força de trabalho.

  5. Insira o provedor do pool de força de trabalho e as credenciais da organização.

  6. Visualize os resultados do app na página Visualização exibida.

    Para mais informações sobre como visualizar os resultados da pesquisa, consulte Veja os resultados da pesquisa.

Para mais informações sobre o console da Federação de identidade da força de trabalho, 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. Google recomenda que você conceda um papel personalizado do IAM ao seu grupo de usuários.

  • Identidade do Google: se você usa o Google Identity, o Google recomenda que você você cria um Grupo do Google que inclui 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 os usuários do pool de força de trabalho a um grupo único.

O Google recomenda que você crie um papel personalizado do IAM para conceder ao seu 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 permissões de recursos do Vertex AI Agent Builder usando 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.

Autorizar o widget de pesquisa

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

  1. Conceder o papel de Leitor do Discovery Engine aos usuários do seu domínio ou colaboradores que precisam fazer chamadas de API de pesquisa.

  2. Gere tokens de autorização para transmitir ao widget:

  3. Siga as etapas em Adicionar um widget com um token de autorização. para passar o token para o 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:

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

    Agent Builder.

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

  3. Acesse a guia Integration > UI.

  4. Clique em Ativar o app da Web.

  5. Se você estiver usando a federação de identidade de colaboradores, selecione um pool de colaboradores de nuvem.

  6. Clique no link para o app da Web.

  7. Insira as credenciais do provedor do pool de força de trabalho e da organização.

  8. Visualize os resultados do app.

  9. Se quiser configurar resultados para o app da Web, acesse Configurar resultados para o widget de pesquisa. Todas as configurações do widget se aplicam ao app da Web.

  10. Opcional: fornecer o app de pesquisa aos usuários por meio dessa página da Web dedicada app, copie o URL e envie-o aos usuários com credenciais de login. Ele pode adicionar o URL do app da Web aos favoritos e acessá-lo para usar o app de pesquisa.

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