Usar o controle de acesso à fonte de dados

Nesta página, descrevemos como aplicar o controle de acesso à fonte de dados para apps de pesquisa em aplicativos de IA.

O controle de acesso às suas fontes de dados nos aplicativos de IA limita os dados que os usuários podem ver 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 seu app de pesquisa. No entanto, você precisa garantir que eles não possam ver conteúdo pelo app que não têm permissão para acessar. Se você tiver configurado um pool de colaboradores em Google Cloud para o provedor de identidade da sua organização, também poderá especificar esse pool em aplicativos de IA. Agora, se um funcionário usar seu app, ele vai receber resultados da pesquisa apenas para documentos a que a conta 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 para o AI Applications, é necessário configurar o provedor de identidade da sua organização no 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 são gerenciados pelo 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 a Identidade do Google. Os usuários finais usam a Identidade do Google para fazer a autenticação antes de acessar recursos do Google ou o Google Workspace.

    • Caso 3: você usa um provedor de identidade de terceiros e sincronizou identidades com a Identidade do Google. No entanto, você ainda usa seu provedor de identidade terceirizado atual para realizar a autenticação. Você configurou o SSO com o Google Identity para que os usuários iniciem 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 recursos do Google Cloud ou o Google Workspace.

  • Federação de provedores de identidade terceirizados: se você usa um provedor de identidade externo, como o Azure AD, o Okta ou o Ping, mas não quer sincronizar suas identidades com o Cloud Identity, configure a federação de identidade da força de trabalho em Google Cloudantes de ativar o controle de acesso à fonte de dados para aplicativos de IA.

    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:

    • 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 3.000 leitores por documento. Cada principal é contabilizado 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 Vertex AI para Pesquisa.
  • 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 com acesso controlado porque eles só podem ser vistos por usuários com acesso de leitura.
  • Para conferir os resultados da UI de apps de pesquisa que usam controle de acesso de terceiros, faça login no console federado ou use o app da Web. Consulte Conferir resultados de apps com controle de acesso.

Antes de começar

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

  • Google Identity: se você usa o Google Identity, siga o procedimento Conectar ao provedor de identidade.
  • Provedor de identidade terceirizado: verifique se você configurou um pool de identidade de colaboradores para seu provedor de identidade terceirizado. 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 pools de identidades da força de trabalho, consulte Gerenciar provedores de pools de identidades da força de trabalho na documentação do IAM.

Conectar ao seu provedor de identidade

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

  1. No console Google Cloud , 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 no 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 escolha 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 estas etapas, dependendo do tipo de fonte 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 como controlado por acesso:

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

  2. Ao seguir as etapas para criar um 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 importar dados em Criar um repositório 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 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 como controlado por acesso:

  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 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 importar dados em Criar um repositório 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 você estiver usando a API, defina GcsSource.dataSchema como document.

Dados não estruturados do BigQuery

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

  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 estiver usando a API, defina BigQuerySource.dataSchema como document.

Dados estruturados do BigQuery

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

  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á enviando, selecione JSONL para dados estruturados com metadados
    • Se você 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 de apps com controle de acesso de terceiros, faça login com as credenciais da sua organização.

Você pode visualizar os resultados da UI de duas maneiras:

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 ver os resultados:

  1. No console Google Cloud , 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 da força de trabalho.

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

  6. Confira os resultados de prévia do app na página Prévia 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 permitir que os usuários pesquisem dados controlados por acesso usando seu app, é necessário conceder acesso a eles 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, recomendamos que crie um Grupo do Google que inclua todos os funcionários que precisam pesquisar. Se você for um 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 membros do pool de força de trabalho 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 do AI Applications usando 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.

Autorizar o widget de pesquisa

Se quiser implantar um widget de pesquisa para um app com controle de acesso, siga estas etapas:

  1. 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 da API Search.

  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.

Ativar o app da Web

O app da Web é um site dedicado gerado pela Vertex AI para Pesquisa em que você e outros usuários com credenciais de login podem usar seu app de pesquisa.

Para oferecer o app de pesquisa aos usuários sem precisar integrar o widget ou a API de pesquisa ao seu aplicativo, forneça o URL do app da Web aos usuários.

Siga estas etapas para ativar o app da Web:

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

    Aplicativos de IA

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

    O app de pesquisa precisa estar associado a pelo menos uma fonte de dados com controle de acesso. Para mais informações, consulte Configurar uma fonte de dados com controle de acesso.

  3. Acesse a guia Integração > Interface.

  4. Clique em Ativar o app da Web.

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

  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. Confira os resultados do seu app.

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

  10. Opcional: para fornecer o app de pesquisa aos usuários por esse app da Web dedicado, copie o URL e envie para os usuários que têm credenciais de login. Eles podem adicionar o URL do app da Web aos favoritos e acessar para usar seu app de pesquisa.

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