Use o controlo de acesso à origem de dados

Esta página descreve como aplicar o controlo de acesso à origem de dados para apps de pesquisa em aplicações de IA.

O controlo de acesso às suas origens de dados nas aplicações de IA limita os dados que os utilizadores podem ver nos resultados da sua app de pesquisa. A Google usa o seu fornecedor de identidade para identificar o utilizador final que está a fazer uma pesquisa e determinar se tem acesso aos documentos devolvidos como resultados.

Por exemplo, suponhamos que os funcionários da sua empresa pesquisam documentos do Confluence através da sua app de pesquisa. No entanto, tem de se certificar de que não podem ver conteúdo através da app ao qual não têm permissão de acesso. Se tiver configurado um workforce pool no Google Cloud fornecedor de identidade da sua organização, também pode especificar esse workforce pool nas Aplicações de IA. Agora, se um funcionário usar a sua app, recebe resultados da pesquisa apenas para documentos aos quais a sua conta já tem acesso no Confluence.

Acerca do controlo de acesso à origem de dados

A ativação do controlo de acesso é um procedimento único.

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

Para ativar o controlo de acesso à origem de dados para aplicações de IA, tem de ter o fornecedor de identidade da sua organização configurado no Google Cloud. São suportados os seguintes frameworks de autenticação:

  • Google Identity:

    • Caso 1: se usar a identidade Google, todas as identidades de utilizadores e grupos de utilizadores estão presentes e são geridas através do Google Cloud. Para mais informações acerca da identidade Google, consulte a documentação da identidade Google.

    • Caso 2: usa um fornecedor de identidade de terceiros e sincronizou identidades com a identidade Google. Os seus utilizadores finais usam a identidade Google para se autenticarem antes de acederem aos recursos Google ou ao Google Workspace.

    • Caso 3: usa um fornecedor de identidade de terceiros e sincronizou identidades com a identidade Google. No entanto, continua a usar o seu fornecedor de identidade de terceiros existente para realizar a autenticação. Configurou o SSO com a identidade Google de modo que os seus utilizadores iniciem sessão através da identidade Google e, em seguida, sejam direcionados para o seu Fornecedor de identidade de terceiros. (É possível que já tenha feito esta sincronização quando configurou outros Google Cloud recursos ou o Google Workspace.)

  • Federação de fornecedores de identidade de terceiros: se usar um fornecedor de identidade externo, por exemplo, o Azure AD, o Okta ou o Ping, mas não quiser sincronizar as suas identidades com o Google Cloud Identity, tem de configurar a federação de identidades da força de trabalho no Google Cloudantes de poder ativar o controlo de acesso à origem de dados para as aplicações de IA.

    Se usar conetores de terceiros, o atributo google.subject tem de ser mapeado para o campo de endereço de email no fornecedor de identidade externo. Seguem-se exemplos de mapeamentos de atributos google.subject e google.groups para fornecedores de identidade usados frequentemente:

    • 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 controlo de acesso tem as seguintes limitações:

  • São permitidos 3000 leitores por documento. Cada principal é contabilizado como um leitor, em que um principal pode ser um grupo ou um utilizador individual.
  • Pode selecionar um fornecedor de identidade por localização suportada pelo Vertex AI Search.
  • Para definir uma origem de dados como controlada por acesso, tem de selecionar esta definição durante a criação do armazenamento de dados. Não pode ativar nem desativar esta definição para um arquivo de dados existente.
  • O separador Dados > Documentos na consola não apresenta dados para origens de dados com controlo de acesso, uma vez que estes dados só devem estar visíveis para utilizadores com acesso de visualização.
  • Para pré-visualizar os resultados da IU para apps de pesquisa que usam o controlo de acesso de terceiros, tem de iniciar sessão na consola federada ou usar a app Web. Consulte o artigo Pré-visualize os resultados para apps com acesso controlado.

Antes de começar

Este procedimento pressupõe que configurou um fornecedor de identidade no seuGoogle Cloud projeto.

  • Identidade Google: se usar a identidade Google, pode avançar para o procedimento Associe o seu fornecedor de identidade.
  • Fornecedor de identidade de terceiros: certifique-se de que configurou um Workload Identity Pool para o seu fornecedor de identidade de terceiros. Verifique se especificou mapeamentos de atributos de assunto e grupo ao configurar o conjunto de recursos humanos. Para obter informações sobre mapeamentos de atributos, consulte Mapeamentos de atributos na documentação da IAM. Para mais informações sobre os Workforce Identity Pools, consulte o artigo Faça a gestão de fornecedores do Workforce Identity Pool na documentação do IAM.

Estabeleça ligação com o seu Fornecedor de identidade

Para especificar um fornecedor de identidade para as Aplicações de IA e ativar o controlo de acesso à origem de dados, siga estes passos:

  1. Na Google Cloud consola, aceda à página Aplicações de IA.

    Aplicações de IA

  2. Aceda à página Definições > Autenticação.

  3. Clique no ícone de edição para a localização que quer atualizar.

  4. Selecione o seu Fornecedor de identidade na caixa de diálogo Adicionar Fornecedor de identidade. Se selecionar um fornecedor de identidade de terceiros, selecione também o conjunto de trabalhadores que se aplica às suas origens de dados.

  5. Clique em Guardar alterações.

Configure uma origem de dados com controlo de acesso

Para aplicar o controlo de acesso a uma origem de dados, siga os passos abaixo consoante o tipo de origem de dados que está a configurar:

Dados não estruturados do Cloud Storage

Quando configurar um repositório de dados para dados não estruturados do Cloud Storage, também tem de carregar metadados da ACL e definir o repositório de dados como controlado por acesso:

  1. Quando preparar os dados, inclua informações da ACL nos metadados através do campo acl_info. Por 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 secção Dados não estruturados do artigo Prepare os dados para carregamento.

  2. Quando seguir os passos para a criação do repositório de dados em Crie um repositório de dados de pesquisa, pode ativar o controlo de acesso fazendo o seguinte na consola ou através da API:

    • Console: quando criar um arquivo de dados, selecione Este arquivo de dados contém informações de controlo de acesso durante a criação do arquivo de dados.
    • API: quando criar o arquivo de dados, inclua a flag "aclEnabled": "true" no seu payload JSON.

  3. Quando seguir os passos para a importação de dados em Crie um arquivo de dados de pesquisa, certifique-se de que faz o seguinte:

    • Carregue os metadados com informações da ACL do mesmo contentor que os seus dados não estruturados
    • Se usar a API, defina GcsSource.dataSchema como document

Dados estruturados do Cloud Storage

Quando configurar um repositório de dados para dados estruturados do Cloud Storage, também tem de carregar metadados da ACL e definir o repositório de dados como controlado por acesso:

  1. Quando preparar os dados, inclua informações da ACL nos metadados através do campo acl_info. Por exemplo:

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

  2. Quando seguir os passos para a criação do repositório de dados em Crie um repositório de dados de pesquisa, pode ativar o controlo de acesso fazendo o seguinte na consola ou através da API:

    • Console: quando criar um arquivo de dados, selecione Este arquivo de dados contém informações de controlo de acesso durante a criação do arquivo de dados.
    • API: quando criar o arquivo de dados, inclua a flag "aclEnabled": "true" no seu payload JSON.

  3. Quando seguir os passos para a importação de dados em Crie um arquivo de dados de pesquisa, certifique-se de que faz o seguinte:

    • Carregue os metadados com informações da ACL do mesmo contentor que os seus dados não estruturados
    • Se usar a API, defina GcsSource.dataSchema como document

Dados não estruturados do BigQuery

Quando configurar um repositório de dados para dados não estruturados do BigQuery, tem de definir o repositório de dados como controlado por acesso e fornecer metadados de LCA usando um esquema predefinido para a Pesquisa do Vertex AI:

  1. Quando 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. Quando seguir os passos em Crie um arquivo de dados de pesquisa, ative o controlo de acesso na consola ou através da API:

    • Console: quando criar um arquivo de dados, selecione Este arquivo de dados contém informações de controlo de acesso durante a criação do arquivo de dados.
    • API: quando criar o arquivo de dados, inclua a flag "aclEnabled": "true" no seu payload JSON.

  4. Quando seguir os passos para a importação de dados em Crie um arquivo de dados de pesquisa, se usar a API, defina BigQuerySource.dataSchema como document.

Dados estruturados do BigQuery

Quando configurar um repositório de dados para dados estruturados do BigQuery, tem de definir o repositório de dados como controlado por acesso e fornecer metadados de LCA através de um esquema predefinido para a Pesquisa do Vertex AI:

  1. Quando 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. Quando seguir os passos em Crie um arquivo de dados de pesquisa, ative o controlo de acesso na consola ou através da API:

    • Console: quando criar um arquivo de dados, selecione Este arquivo de dados contém informações de controlo de acesso durante a criação do arquivo de dados.
    • API: quando criar o arquivo de dados, inclua a flag "aclEnabled": "true" no seu payload JSON.

  4. Quando seguir os passos para a importação de dados em Crie um arquivo de dados de pesquisa, certifique-se de que faz o seguinte:

    • Se usar a consola, quando especificar o tipo de dados que está a carregar, selecione JSONL para dados estruturados com metadados
    • Se usar a API, defina BigQuerySource.dataSchema como document

Pré-visualize os resultados das apps com controlo de acesso de terceiros

A pré-visualização dos resultados na consola para apps com controlo de acesso de terceiros requer que inicie sessão com as credenciais da sua organização.

Pode pré-visualizar os resultados da IU de duas formas:

Pré-visualize os resultados na consola da federação de identidade da força de trabalho

Siga estes passos para usar a consola Workforce Identity Federation para ver os resultados:

  1. Na Google Cloud consola, aceda à página Aplicações de IA.

    Aplicações de IA

  2. Clique no nome da app de pesquisa cujos resultados quer pré-visualizar.

  3. Aceda à página Pré-visualizar.

  4. Clique em Pré-visualizar com identidade federada para aceder à consola da federação de identidade da força de trabalho.

  5. Introduza o fornecedor do workforce pool e as credenciais da organização.

  6. Pré-visualize os resultados da sua app na página Pré-visualizar apresentada.

    Para mais informações sobre a pré-visualização dos resultados da pesquisa, consulte o artigo Obtenha resultados da pesquisa.

Para mais informações acerca da consola da federação de identidade da força de trabalho, consulte o artigo Acerca da consola (federada).

Conceda autorizações de pesquisa aos seus utilizadores

Para dar aos seus utilizadores a capacidade de pesquisar dados controlados por acesso através da sua app, tem de conceder acesso aos utilizadores no seu domínio ou conjunto de trabalhadores. A Google recomenda que conceda uma função de IAM personalizada ao seu grupo de utilizadores.

  • Identidade Google: se usar a Identidade Google, a Google recomenda que crie um grupo Google que inclua todos os funcionários que precisam de pesquisar. Se for um administrador do Google Workspace, pode incluir todos os utilizadores de uma organização num grupo Google seguindo os passos descritos no artigo Adicione todos os utilizadores da sua organização a um grupo.
  • Fornecedor de identidade de terceiros: se usar um fornecedor de identidade externo, por exemplo, o Okta ou o Azure AD, adicione todos os membros do seu conjunto de colaboradores a um único grupo.

A Google recomenda que crie uma função de IAM personalizada para conceder ao seu grupo de utilizadores, usando as seguintes autorizações:

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

Para mais informações sobre as autorizações para recursos das Aplicações de IA através da Identity and Access Management (IAM), consulte o artigo Controlo de acesso com a IAM.

Para mais informações sobre funções personalizadas, consulte o artigo Funções personalizadas na documentação do IAM.

Autorize o widget de pesquisa

Se quiser implementar um widget de pesquisa para uma app com controlo de acesso, siga estes passos:

  1. Conceda a função de visualizador do motor de descoberta aos utilizadores no seu domínio ou conjunto de talentos que precisam de fazer chamadas à API Search.

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

  3. Siga os passos em Adicione um widget com um token de autorização para transmitir o token ao seu widget.

Ative a app Web

A app Web é um site dedicado gerado pelo Vertex AI Search onde você e quaisquer outros utilizadores com credenciais de início de sessão podem usar a sua app de pesquisa.

Para disponibilizar a app de pesquisa aos utilizadores sem ter de integrar o widget de pesquisa nem a API de pesquisa na sua própria aplicação, pode fornecer o URL da app Web aos seus utilizadores.

Siga estes passos para ativar a app Web:

  1. Na Google Cloud consola, aceda à página Aplicações de IA.

    Aplicações de IA

  2. Clique no nome da app de pesquisa para a qual quer criar uma app Web.

    A app de pesquisa tem de estar associada a, pelo menos, uma origem de dados com controlo de acesso. Para mais informações, consulte o artigo Configure uma origem de dados com controlo de acesso.

  3. Aceda ao separador Integração > IU.

  4. Clique em Ativar a app Web.

  5. Se estiver a usar a federação de identidade da força de trabalho, selecione um fornecedor do Workforce Pool.

  6. Clique no link para a sua app Web.

  7. Introduza o fornecedor do workforce pool e as credenciais da organização.

  8. Pré-visualize os resultados da sua app.

  9. Para configurar os resultados da app Web, aceda a Configure os resultados do widget de pesquisa. Todas as configurações do widget também se aplicam à app Web.

  10. Opcional: para disponibilizar a app de pesquisa aos seus utilizadores através desta app Web dedicada, copie o URL e envie-o aos utilizadores que tenham credenciais de início de sessão. Podem adicionar o URL da app Web aos favoritos e aceder ao mesmo para usar a sua app de pesquisa.

Para mais informações sobre como receber resultados da pesquisa, consulte o artigo Receba resultados da pesquisa.