Configurar o controle de acesso à fonte de dados

Nesta página, descrevemos como aplicar o controle de acesso à fonte de dados para apps de pesquisa na Pesquisa de agentes.

O controle de acesso às suas fontes de dados na Pesquisa de agentes limita os dados que os usuários podem visualizar nos resultados do app de pesquisa. O Google usa seu provedor de identidade para identificar o usuário final que está fazendo 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 o app de pesquisa. No entanto, você precisa garantir que eles não possam visualizar conteúdo no app que não têm permissão para acessar. Se você configurou um pool de força de trabalho no Google Cloud provedor de identidade da sua organização, então também pode especificar esse pool na Pesquisa de agentes. Agora, se um funcionário usar o app, ele vai receber resultados de pesquisa apenas para documentos 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 na Pesquisa de agentes, é necessário que o provedor de identidade da sua organização esteja configurado em Google Cloud. As seguintes estruturas de autenticação são compatíveis:

  • Google Identity:

    • Caso 1: se você usa o Google Identity, todas as identidades e grupos de usuários estão presentes e gerenciados por Google Cloud. Para mais informações sobre o Google Identity, consulte a documentação do Google Identity.

    • Caso 2: você usa um provedor de identidade de terceiros e sincronizou identidades com o Google Identity. Seus usuários finais usam o Google Identity para autenticar antes de acessar os recursos do Google ou o Google Workspace.

    • Caso 3: você usa um provedor de identidade de terceiros e sincronizou identidades com o Google Identity. No entanto, você ainda está usando o provedor de identidade de terceiros para realizar a autenticação. Você configurou o SSO com o Google Identity para que os usuários comecem o login usando o Google Identity e sejam direcionados ao provedor de identidade de terceiros. Talvez você já tenha feito essa sincronização ao configurar outros Google Cloud recursos ou o Google Workspace.

  • Federação de provedores de identidade de terceiros: se você usa um provedor de identidade externo, por exemplo, o Microsoft Entra ID, o Okta ou o Ping, mas não quer sincronizar suas identidades com o Google Cloud Identity, configure a federação de identidade de colaboradores em Google Cloud antes de ativar o controle de acesso à fonte de dados para a Pesquisa de agentes.

    Se você usa conectores de terceiros, o atributo google.subject precisa ser mapeado para o campo de endereço de e-mail no provedor de identidade externo. Confira a seguir exemplos de mapeamentos de atributos google.subject e google.groups para provedores de identidade usados com frequência:

Limitações

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

  • São permitidos 3.000 leitores por documento. Cada principal conta como um leitor, e um principal pode ser um grupo ou um usuário individual.
  • É possível selecionar um provedor de identidade por local compatível com a Pesquisa de agentes.
  • 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 para fontes de dados controladas por acesso, porque esses dados só podem ser visíveis para usuários que têm acesso de visualização.
  • Para conferir os resultados da UI em apps de pesquisa que usam controle de acesso de terceiros, faça login no console federado. Consulte Visualizar resultados para apps controlados por acesso.

Antes de começar

Este procedimento pressupõe que você tenha configurado um provedor de identidade no seu Google Cloud projeto.

  • Google Identity: se você usa o Google Identity, siga para o procedimento Conectar ao seu 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 colaboradores. 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 provedores de pools de identidade de colaboradores na documentação do IAM.

Conectar ao seu provedor de identidade

Para especificar um provedor de identidade para a Pesquisa de agentes e ativar o controle de acesso à fonte de dados, siga estas etapas:

  1. No Google Cloud console, acesse a página Aplicativos de IA.

    Aplicativos de IA

  2. Acesse a página Configurações > Autenticação.

  3. Clique no ícone de edição do 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, também selecione o pool de colaboradores 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 estas etapas, dependendo do 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 dos metadados da ACL e definir o repositório de dados como controlado por acesso:

  1. Ao preparar os dados, inclua informações da 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 de Preparar dados para ingestão.

  2. Ao seguir as etapas para a criação do 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.
    • 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 um repositório de dados de pesquisa, faça o seguinte:

    • Faça upload dos metadados com informações da ACL do mesmo bucket que os dados não estruturados.
    • Se você 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, também é necessário fazer upload dos metadados da ACL e definir o repositório de dados como controlado por acesso:

  1. Ao preparar os dados, inclua informações da 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 a criação do 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.
    • 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 um repositório de dados de pesquisa, faça o seguinte:

    • Faça upload dos metadados com informações da ACL do mesmo bucket que os dados não estruturados.
    • Se você 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 de dados como controlado por acesso e fornecer metadados da ACL usando um esquema predefinido para a Pesquisa de agentes:

  1. Ao preparar os dados, especifique o seguinte esquema. 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 um repositório 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.
    • API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.

  4. Ao seguir as etapas para 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 de dados como controlado por acesso e fornecer metadados da ACL usando um esquema predefinido para a Pesquisa de agentes:

  1. Ao preparar os dados, especifique o seguinte esquema. 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 um repositório 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.
    • API: ao criar o repositório de dados, inclua a flag "aclEnabled": "true" no payload JSON.

  4. Ao seguir as etapas para 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á fazendo upload, selecione JSONL para dados estruturados com metadados.
    • Se você estiver usando a API, defina BigQuerySource.dataSchema como document

Visualizar resultados no console da federação de identidade de colaboradores

Para visualizar os resultados de apps com controle de acesso de terceiros no Google Cloud console, faça login com as credenciais da organização.

Para visualizar os resultados da UI, siga estas etapas:

  1. No Google Cloud console, acesse a página Aplicativos de IA.

    Aplicativos de IA

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

  3. Acesse a página Visualização.

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

  5. Insira o provedor do pool de colaboradores e as credenciais da organização.

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

    Para mais informações sobre como visualizar os 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 que os usuários possam pesquisar dados controlados por acesso usando seu app, é necessário conceder acesso aos usuários no seu domínio ou pool de colaboradores. O Google recomenda que você conceda um papel personalizado do IAM ao seu grupo de usuários.

  • Google Identity: se você usa o Google Identity, o Google recomenda que você crie 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, por exemplo, o Okta ou o Microsoft Entra ID, adicione todos no pool de colaboradores a um único grupo.

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
  • discoveryengine.widgetConfigs.get

Para mais informações sobre permissões para recursos da Pesquisa de agentes usando o Identity and Access Management (IAM), consulte Controle de acesso com IAM.

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

Autorizar o widget de pesquisa

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

  1. Conceda o papel de Leitor do Discovery Engine aos usuários no seu domínio ou pool de 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 transmitir o token ao widget.

A seguir

Receber resultados da pesquisa.