Mapear identidades externas

As empresas geralmente gerenciam identidades (usuários e grupos de usuários) usando um provedor de identidade (IDP). No entanto, aplicativos personalizados criados internamente por uma empresa podem permitir que os clientes criem novos grupos de usuários definidos localmente nesse aplicativo. Esses grupos de usuários específicos do aplicativo ou IDs de usuários secundários são chamados de identidades externas.

Por que configurar o mapeamento de identidade?

Para garantir que o Google possa aplicar o controle de acesso corretamente, mapeie as identidades do IDP para identidades externas dos aplicativos personalizados que você planeja usar com o Gemini Enterprise.

Para aplicar o controle de acesso aos resultados do app, o Google usa o IDP como a fonte da verdade para determinar a quais dados seus usuários têm acesso. As empresas costumam conectar o IDP a outras soluções de SaaS para que um funcionário possa usar um único conjunto de credenciais corporativas para fazer login e acessar todos os recursos da empresa.

Se você tiver identidades externas definidas por aplicativos que planeja conectar ao seu app, como aplicativos personalizados, o IDP não será a única fonte da verdade para o controle de acesso.

Por exemplo, digamos que "JaneDoe" exista na organização de exemplo, com o domínio "example.com". O ID no IDP é definido como "JaneDoe@example.com". O mesmo usuário tem um ID separado em um aplicativo personalizado como "JDoe". O IDP pode não estar ciente desse ID. Por isso, o Gemini Enterprise não recebe informações sobre os IDs de aplicativos personalizados pelo IDP.

No Gemini Enterprise, os mapeamentos de identidade são armazenados em um repositório de mapeamento de identidade que você cria e importa os mapeamentos. Se você planeja usar um conector personalizado, pode vincular o repositório de mapeamento de identidade ao repositório de dados do conector personalizado e, em seguida, atualizar os metadados da ACL do repositório de dados com informações sobre suas identidades externas.

Antes de começar

Antes de configurar o mapeamento de identidade, conecte seu provedor de identidade ao seu Google Cloud projeto.

Preparar entradas de mapeamento de identidade

Prepare as entradas de mapeamento de identidade para importação. Os mapeamentos de identidade precisam ser formatados como no exemplo a seguir:

{
  "identity_mapping_entries": [
    {
      "external_identity": "u1",
      "user_id": "user1@example.com"
    },
    {
      "external_identity": "u2",
      "user_id": "user2@example.com"
    },
    {
      "external_identity": "gABC",
      "group_id": "groupABC@example.com"
    }
  ]
}

Por exemplo, o gráfico a seguir representa um exemplo de participação de grupo de usuários, em que Ext representa grupos externos. Esse gráfico mostra um exemplo de relação entre grupos externos e usuários e grupos de IDP.

Relacionamento de identidade externa com usuários e grupos do IdP.

Esse gráfico de participação de grupo de usuários teria o seguinte mapeamento:

{
  "identity_mapping_entries": [
    {
      "external_identity": "Ext1",
      "user_id": "IDPUser1@example.com"
    },
    {
      "external_identity": "Ext2",
      "user_id": "IDPUser1@example.com"
    },
    {
      "external_identity": "Ext2",
      "user_id": "IDPUser2@example.com"
    },
    {
      "external_identity": "Ext3",
      "user_id": "IDPUser2@example.com"
    },
    {
      "external_identity": "Ext3",
      "group_id": "IDPGroup1@example.com"
    },
    {
      "external_identity": "Ext3",
      "group_id": "IDPGroup2@example.com"
    }
  ]
}

As participações de identidade aninhadas, em que identidades externas têm identidades filhas, precisam ser niveladas.

O Google pressupõe que o conector envia um ID principal para uma identidade externa. Por exemplo, importe o ID do grupo em vez do nome, porque o nome pode ser alterado durante a vida útil do grupo no aplicativo personalizado.

Configurar o mapeamento de identidade

Use os procedimentos a seguir para configurar o mapeamento de identidade no Gemini Enterprise entre o IDP e as identidades externas. Nas etapas a seguir, você vai criar um repositório de mapeamento de identidade e importar os mapeamentos de identidade preparados. Se você planeja usar um conector personalizado, também vai criar um novo repositório de dados vinculado ao repositório de mapeamento de identidade.

Criar um repositório de mapeamento de identidade

A primeira etapa é configurar um repositório de mapeamento de identidade. Esse é o recurso pai em que todos os mapeamentos de identidade são armazenados.

Ao criar o repositório de mapeamento de identidade, ele busca automaticamente a configuração do IDP que você conectou ao projeto do Gemini Enterprise.

  1. Para criar um repositório de mapeamento de identidade, execute o comando a seguir usando o identityMappingStores.create método:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?identityMappingStoreId=IDENTITY_MAPPING_STORE_ID" \
-d '{
  "name": "projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"
}'

    Substitua:

    • PROJECT_ID: ID do projeto.
    • IDENTITY_MAPPING_STORE_ID: o ID exclusivo do repositório de mapeamento de identidade. Por exemplo, test-id-mapping-store.

Importar mapeamentos de identidade

Depois de criar o repositório de mapeamento de identidade, importe as entradas de mapeamento de identidade preparadas. É possível importar mapeamentos de identidade usando uma origem inline (opção 1) ou do Cloud Storage (opção 2).

Ao importar do Cloud Storage, os seguintes formatos e restrições se aplicam:

  • Formatos permitidos: os arquivos de entrada precisam estar no formato NDJSON (.ndjson) ou JSON Lines (.jsonl), com cada linha representando uma única entrada de mapeamento de identidade.
  • Restrições de tamanho de arquivo: cada arquivo não pode exceder 2 GB.
  • Número de restrições de mapeamentos de identidade: é possível importar até 500,000 mapeamentos de identidade externa em uma operação de importação.
  • Restrições de contagem de arquivos: é possível especificar até 2,000 arquivos na lista inputUris. Se você usar curingas, o limite será aplicado ao número total de arquivos após a expansão do curinga.

Opção 1: importar usando a origem inline

  1. Para importar os mapeamentos de identidade usando uma origem inline, execute o comando a seguir usando o importIdentityMappings método:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \
-d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'

    Substitua:

    • PROJECT_ID: ID do projeto.
    • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
      • us para a multirregião dos EUA
      • eu para a multirregião da UE
      • global para o local global
      Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
    • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
    • IDENTITY_MAPPING_STORE_ID: o ID exclusivo do repositório de mapeamento de identidade.
    • IDENTITY_MAPPINGS_JSON: os mapeamentos de identidade preparados no formato JSON.

  2. Se você planeja criar um conector personalizado e usar identidades externas, acesse Vincular repositórios de dados personalizados ao repositório de mapeamento de identidade. Caso contrário, pule para Atualizar metadados da ACL.

Opção 2: importar do Cloud Storage

  1. Para importar os mapeamentos de identidade do Cloud Storage, execute o comando a seguir usando o importIdentityMappings método:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \
-d '{
  "gcsSource": {
    "inputUris": ["gs://BUCKET_NAME/FILE_PATH"]
  },
  "errorConfig": {
    "gcsPrefix": "gs://BUCKET_NAME/ERROR_DIR"
  },
  "reconciliationMode": "FULL"
}'

    Substitua:

    • PROJECT_ID: ID do projeto.
    • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
      • us para a multirregião dos EUA
      • eu para a multirregião da UE
      • global para o local global
      Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
    • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
    • IDENTITY_MAPPING_STORE_ID: o ID exclusivo do repositório de mapeamento de identidade.
    • BUCKET_NAME: o nome do bucket do Cloud Storage.
    • FILE_PATH: o caminho para o arquivo de mapeamentos de identidade no Cloud Storage.
    • ERROR_DIR: o diretório no Cloud Storage em que os registros de erros serão armazenados.

  2. Se você planeja criar um conector personalizado e usar identidades externas, acesse Vincular repositórios de dados personalizados ao repositório de mapeamento de identidade. Caso contrário, pule para Atualizar metadados da ACL.

Vincular repositórios de dados personalizados ao repositório de mapeamento de identidade

Esse procedimento só é necessário se você criar um conector personalizado. Se você não estiver criando um conector personalizado, pule esta etapa.

Para conectores personalizados, o repositório de mapeamento de identidade precisa ser vinculado ao repositório de dados antes que uma identidade externa possa ser associada aos documentos. A definição desse campo só é permitida durante a criação do repositório de dados.

  1. Para vincular um repositório de dados ao repositório de mapeamento de identidade, especifique identity_mapping_store durante a criação do repositório de dados usando o Datastores.create método.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"  \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID \
-d '{
    ...
    "identity_mapping_store": "IDENTITY_MAPPING_STORE_NAME"
}'

    Substitua:

    • PROJECT_ID: ID do projeto.
    • DATA_STORE_ID: o ID do repositório de dados que você quer criar. Esse ID só pode conter letras minúsculas, dígitos, sublinhados e hífens.
    • IDENTITY_MAPPING_STORE_NAME: o nome completo do recurso do repositório de mapeamento de identidade. Por exemplo, projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store. Depois de criar um repositório de dados, esse nome não pode ser atualizado.

Adicionar metadados da ACL

Inclua metadados da ACL no objeto AclInfo dos seus documentos.

Quando um usuário envia uma solicitação de pesquisa e documentos cujos metadados da ACL incluem identidades externas são buscados, essas identidades externas são avaliadas. Se a identidade do usuário (groupID ou userID) for mapeada para uma identidade externa (externalEntityId) associada a um documento, o usuário terá acesso a esse documento.

Por exemplo, digamos que você tenha criado um conector personalizado para o Jira. Um problema específico do Jira pode ser acessado por determinados usuários do IDP, determinados grupos do IDP e uma função de administrador. Para permitir que esse problema seja acessado por essas pessoas nos resultados da pesquisa, você pode criar um repositório de mapeamento de identidade e mapear usuários e grupos do IDP para identidades externas específicas do Jira. Vincule o repositório de mapeamento de identidade ao repositório de dados do Jira. Em seguida, crie documentos nos repositórios de dados do Jira com aclInfo configurado com os usuários do IDP, grupos do IDP e identidades externas que precisam ter acesso a esses documentos.

Para atualizar os metadados da ACL com informações sobre suas identidades externas, use o formato a seguir para especificar as identidades externas e os IDs de usuários e grupos associados.

{
  "aclInfo": {
    "readers": [
      {
        "principals": [
          {
            "groupId": "group_1"
          },
          {
            "userId": "user_1"
          },
          {
            "externalEntityId": "external_id1"
          }

        ]
      }
    ]
  }
}

Para mais informações sobre como atualizar os metadados da ACL, consulte Configurar uma fonte de dados com controle de acesso.

Gerenciar mapeamentos de identidade

É possível listar mapeamentos de identidade em um repositório de identidade ou limpar um repositório de identidade definindo-os por uma origem inline ou usando uma condição de filtro.

As tarefas de gerenciamento disponíveis para o mapeamento de identidade são:

Listar mapeamentos de identidade

  1. Para listar mapeamentos de identidade, execute o comando a seguir usando o listIdentityMappings método:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:listIdentityMappings?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

    Substitua:

    • PROJECT_ID: ID do projeto.
    • PAGE_SIZE: número máximo de repositórios de mapeamento de identidade a serem retornados. Se não for especificado, o padrão será 100. O valor máximo permitido é 1.000. Valores maiores que 1.000 serão convertidos para 1.000.
    • PAGE_TOKEN: um token de página, recebido de uma chamada ListIdentityMappingStores anterior. Forneça isso para recuperar a página subsequente.

Limpar usando a origem inline

É possível limpar as entradas especificadas de um repositório de mapeamento de identidade fornecendo um arquivo JSON de quais identidades limpar.

  1. Para limpar mapeamentos de identidade usando a origem inline, execute o comando a seguir usando o purgeIdentityMappings método:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \
-d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'

    Substitua:

    • PROJECT_ID: ID do projeto.
    • IDENTITY_MAPPING_STORE_ID: o ID exclusivo do repositório de mapeamento de identidade.
    • IDENTITY_MAPPING_STORE_NAME: o nome da loja de mapeamento de identidade.
    • IDENTITY_MAPPINGS_JSON: os mapeamentos de identidade a serem limpos.

Limpar usando uma condição de filtro

É possível limpar as entradas especificadas de um repositório de mapeamento de identidade filtrando as entradas por horário de atualização, identidade externa ou todas as entradas.

  1. Para limpar mapeamentos de identidade usando uma condição de filtro, execute o comando a seguir usando o purgeIdentityMappings método:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \
-d '{"identity_mapping_store":"IDENTITY_MAPPING_STORE_NAME", "filter": "FILTER_CONDITION"}'

    Substitua:

    • PROJECT_ID: ID do projeto.
    • IDENTITY_MAPPING_STORE_ID: o ID exclusivo do repositório de mapeamento de identidade.
    • IDENTITY_MAPPING_STORE_NAME: o nome da loja de mapeamento de identidade.
    • FILTER_CONDITION: um dos seguintes tipos de filtro:
      • Horário de atualização. Por exemplo, update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z">
      • Identidade externa. Por exemplo, external_id = "id1"
      • Todos os mapeamentos de identidade. Por exemplo, *

Gerenciar repositórios de mapeamento de identidade

É possível receber, excluir, listar e limpar repositórios de mapeamento de identidade.

Receber repositório de mapeamento de identidade

  1. Para receber um repositório de mapeamento de identidade, execute o comando a seguir usando o identityMappingStores.get método:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"

    Substitua:

    • PROJECT_ID: ID do projeto.
    • IDENTITY_MAPPING_STORE_ID: o ID exclusivo do repositório de mapeamento de identidade.
    • IDENTITY_MAPPING_STORE_NAME: o nome da loja de mapeamento de identidade.

Listar repositórios de mapeamento de identidade

  1. Para listar repositórios de mapeamento de identidade, execute o comando a seguir usando o identityMappingStores.list método:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

    Substitua:

    • PROJECT_ID: ID do projeto.
    • PAGE_SIZE: número máximo de repositórios de mapeamento de identidade a serem retornados. Se não for especificado, o padrão será 100. O valor máximo permitido é 1.000. Valores maiores que 1.000 serão convertidos para 1.000.
    • PAGE_TOKEN: um token de página, recebido de uma chamada ListIdentityMappingStores anterior. Forneça isso para recuperar a página subsequente.

Excluir repositórios de mapeamento de identidade

Para excluir um repositório de mapeamento de identidade, ele não pode estar vinculado a um repositório de dados, e nenhum mapeamento de identidade pode estar presente no repositório de mapeamento de identidade.

  1. Para excluir um repositório de mapeamento de identidade, execute o comando a seguir usando o identityMappingStores.delete método:

    curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"

    Substitua:

    • PROJECT_ID: ID do projeto.
    • IDENTITY_MAPPING_STORE_ID: o ID exclusivo do repositório de mapeamento de identidade.
    • IDENTITY_MAPPING_STORE_NAME: o nome da loja de mapeamento de identidade.