Normalmente, as empresas 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 no aplicativo. Esses grupos de usuários específicos do aplicativo ou IDs de usuário 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 de apps, o Google usa o IdP como fonte de verdade para determinar a quais dados seus usuários têm acesso. As empresas geralmente conectam 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 de 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 talvez não conheça esse 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. Se você planeja usar um conector personalizado, vincule o repositório de mapeamento de identidade ao repositório de dados do conector personalizado e atualize 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 projeto Google Cloud .
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 uma associação de grupo de usuários de exemplo, em que Ext representa grupos externos. Este gráfico mostra um exemplo de relação entre grupos externos e usuários e grupos do IdP.
Esse gráfico de associaçã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 associações de identidades aninhadas, em que identidades externas têm identidades filhas, precisam ser simplificadas.
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 seu IdP e suas identidades externas. Nas etapas a seguir, você vai criar um repositório de mapeamento de identidade e importar os mapeamentos que preparou. Se você planeja usar um conector personalizado, também vai criar um 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 principal em que todos os mapeamentos de identidade são armazenados.
Quando você cria o repositório de mapeamento de identidade, ele busca automaticamente a configuração do IdP do IdP conectado ao seu projeto do Gemini Enterprise.
Para criar um armazenamento de mapeamento de identidade, execute o seguinte comando usando o método
identityMappingStores.create: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 que você preparou.
Para importar seus mapeamentos de identidade, execute o seguinte comando usando o método
importIdentityMappings: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:importIdentityMappings" \ -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_MAPPINGS_JSON: os mapeamentos de identidade preparados no formato JSON.
Em seguida, se você planeja criar um conector personalizado e usar identidades externas, acesse Vincular repositórios de dados personalizados ao repositório de mapeamento de identidades. Caso contrário, pule para Atualizar metadados de 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 armazenamento de mapeamento de identidade precisa ser vinculado ao armazenamento de dados antes que uma identidade externa possa ser associada aos documentos dela. A definição desse campo só é permitida durante a criação do repositório de dados.
Para vincular um repositório de dados ao repositório de mapeamento de identidade, especifique
identity_mapping_storedurante a criação do repositório de dados usando o métodoDatastores.create.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. Ele 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 de ACL
Inclua metadados de ACL no objeto AclInfo dos seus documentos.
Quando um usuário envia uma solicitação de pesquisa e os documentos cujos metadados de 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 determinado problema do Jira
pode ser acessado por usuários e grupos específicos do IdP, além de uma função de
administrador. Para permitir que o problema seja acessível para essas pessoas nos resultados da pesquisa, crie um repositório de mapeamento de identidades e mapeie 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, grupos e identidades externas do IdP que
devem ter acesso a esses documentos.
Para atualizar os metadados da ACL com informações sobre suas identidades externas, use o seguinte formato para especificar as identidades externas e os IDs de usuário e grupo associados.
{
"aclInfo": {
"readers": [
{
"principals": [
{
"groupId": "group_1"
},
{
"userId": "user_1"
},
{
"externalEntityId": "external_id1"
}
]
}
]
}
}
Para mais informações sobre como atualizar metadados de ACL, consulte Configurar uma fonte de dados com controle de acesso.
Gerenciar mapeamentos de identidade
É possível listar mapeamentos de identidade em um armazenamento de identidades ou limpar um armazenamento de identidades definindo-os por uma fonte inline ou usando uma condição de filtro.
As tarefas de gerenciamento disponíveis para o mapeamento de identidades são:
- Listar mapeamentos de identidade
- Excluir usando a fonte in-line
- Excluir usando uma condição de filtro
Listar mapeamentos de identidade
Para listar os mapeamentos de identidade, execute o seguinte comando usando o método
listIdentityMappings: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 chamadaListIdentityMappingStoresanterior. Forneça isso para recuperar a página seguinte.
Remover usando fonte inline
É possível limpar entradas específicas de um repositório de mapeamento de identidade fornecendo um arquivo JSON com as identidades a serem limpas.
Para limpar os mapeamentos de identidade usando uma origem inline, execute o seguinte comando usando o método
purgeIdentityMappings: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 do repositório de mapeamento de identidade.IDENTITY_MAPPINGS_JSON: os mapeamentos de identidade a serem excluídos.
Limpar usando uma condição de filtro
É possível limpar entradas especificadas de um repositório de mapeamento de identidade filtrando por entradas por hora de atualização, identidade externa ou todas as entradas.
Para limpar os mapeamentos de identidade usando uma condição de filtro, execute o seguinte comando usando o método
purgeIdentityMappings: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 do repositório de mapeamento de identidade.FILTER_CONDITION: um dos seguintes tipos de filtro:- Atualize o horário. 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 o armazenamento de mapeamento de identidade
Para receber um armazenamento de mapeamento de identidade, execute o seguinte comando usando o método
identityMappingStores.get: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 do repositório de mapeamento de identidade.
Listar lojas de mapeamento de identidade
Para listar os armazenamentos de mapeamento de identidade, execute o seguinte comando usando o método
identityMappingStores.list: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 chamadaListIdentityMappingStoresanterior. Forneça isso para recuperar a página seguinte.
Excluir armazenamentos 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 não pode haver mapeamentos de identidade no repositório.
Para excluir um armazenamento de mapeamento de identidade, execute o seguinte comando usando o método
identityMappingStores.delete: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 do repositório de mapeamento de identidade.