Normalmente, as empresas gerem identidades (utilizadores e grupos de utilizadores) através de um fornecedor de identidade (IDP). No entanto, as aplicações personalizadas que uma empresa criou internamente podem permitir que os clientes criem novos grupos de utilizadores definidos localmente nessa aplicação. Estes grupos de utilizadores específicos da aplicação ou IDs de utilizadores secundários são denominados identidades externas.
Por que motivo deve configurar o mapeamento da identidade?
Para garantir que a Google pode aplicar o controlo de acesso corretamente, mapeie as identidades do seu IDP para quaisquer identidades externas das aplicações personalizadas que planeia usar com o Gemini Enterprise.
Para aplicar o controlo de acesso aos resultados das apps, a Google usa o IdP como fonte de informação para determinar a que dados os seus utilizadores têm acesso. As empresas associam frequentemente o respetivo IDP a outras soluções de SaaS para que um funcionário possa usar um único conjunto de credenciais corporativas para iniciar sessão e aceder a todos os recursos da empresa.
Se tiver identidades externas definidas através de aplicações que planeia associar à sua app, como aplicações personalizadas, o IdP não é a única fonte de informações fidedignas para o controlo de acesso.
Por exemplo, suponhamos que "JaneDoe" existe na organização de exemplo, com o domínio "example.com". O ID no IDP está definido como "JaneDoe@example.com". O mesmo utilizador tem um ID separado numa aplicação personalizada como "JDoe". O IDP pode não ter conhecimento deste ID. Por este motivo, o Gemini Enterprise não recebe informações sobre os IDs das aplicações personalizadas através do IDP.
No Gemini Enterprise, os mapeamentos de identidade são armazenados num armazenamento de mapeamento de identidades que cria e para o qual importa os mapeamentos. Se planeia usar um conetor personalizado, pode associar o armazenamento de mapeamento de identidades ao armazenamento de dados do conetor personalizado e, em seguida, atualizar os metadados da ACL do armazenamento de dados com informações sobre as suas identidades externas.
Antes de começar
Antes de configurar o mapeamento de identidades, associe o seu fornecedor de identidade ao seu Google Cloud projeto.
Prepare entradas de mapeamento da identidade
Prepare as entradas de mapeamento de identidade para importação. Os mapeamentos de identidades devem ser formatados como no exemplo seguinte:
{
"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 seguinte representa um exemplo de associação de grupos de utilizadores,
em que Ext representa grupos externos. Este gráfico mostra um exemplo de relação
entre grupos externos e utilizadores e grupos do IdP.
Este gráfico de associação de grupos de utilizadores 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 as identidades externas têm identidades secundárias, têm de ser simplificadas.
A Google assume que o conector envia um ID principal para uma identidade externa. Por exemplo, importe o ID do grupo em vez do nome do grupo, porque o nome pode ser alterado ao longo da duração do grupo na aplicação personalizada.
Configure o mapeamento da identidade
Use os procedimentos seguintes para configurar o mapeamento de identidades no Gemini Enterprise entre o seu IdP e as suas identidades externas. Nos passos seguintes, vai criar um armazenamento de mapeamento de identidades e importar os mapeamentos de identidades que preparou. Se planeia usar um conetor personalizado, também cria um novo arquivo de dados associado ao arquivo de mapeamento de identidades.
Crie uma loja de mapeamento de identidades
O primeiro passo é configurar um armazenamento de mapeamento de identidades. Este é o recurso principal no qual todos os mapeamentos de identidade são armazenados.
Quando cria o armazenamento de mapeamento de identidades, este obtém automaticamente a configuração do IDP do IDP que associou ao seu projeto do Gemini Enterprise.
Para criar uma loja de mapeamento de identidades, execute o seguinte comando através do 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 o seguinte:
PROJECT_ID: o ID do seu projeto.IDENTITY_MAPPING_STORE_ID: o ID exclusivo da loja de mapeamento de identidades. Por exemplo,test-id-mapping-store.
Importe mapeamentos da identidade
Depois de criar a loja de mapeamento de identidade, importe as entradas de mapeamentos de identidade que preparou.
Para importar os mapeamentos de identidade, execute o seguinte comando através do 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 o seguinte:
PROJECT_ID: o ID do seu projeto.IDENTITY_MAPPING_STORE_ID: o ID exclusivo da loja de mapeamento de identidade.IDENTITY_MAPPINGS_JSON: os mapeamentos de identidades preparados no formato JSON.
Em seguida, se planeia criar um conector personalizado e usar identidades externas, aceda a Associar arquivos de dados personalizados ao arquivo de mapeamento de identidades. Caso contrário, avance para Atualizar metadados da LCA.
Associe lojas de dados personalizadas à loja de mapeamento de identidades
Este procedimento só é necessário se criar um conetor personalizado. Se não estiver a criar um conetor personalizado, ignore este passo.
Para os conetores personalizados, o armazenamento de mapeamento de identidades tem de estar associado ao armazenamento de dados antes de uma identidade externa poder ser associada aos respetivos documentos. A definição deste campo só é permitida durante a criação do armazenamento de dados.
Para associar um arquivo de dados ao arquivo de mapeamento de identidades, especifique
identity_mapping_storedurante a criação do arquivo de dados através do 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 o seguinte:
PROJECT_ID: o ID do seu projeto.DATA_STORE_ID: o ID do armazenamento de dados que quer criar. Este ID só pode conter letras minúsculas, dígitos, sublinhados e hífenes.IDENTITY_MAPPING_STORE_NAME: o nome completo do recurso da loja de mapeamento de identidades. Por exemplo,projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store. Depois de criar um arquivo de dados, não é possível atualizar este nome.
Adicione metadados de LCA
Inclua metadados de ACL no objeto AclInfo para os seus documentos.
Quando um utilizador envia um pedido de pesquisa e são obtidos documentos cujos metadados de LCA incluem identidades externas, essas identidades externas são avaliadas.
Se a identidade do utilizador (groupID ou userID) estiver mapeada para uma identidade externa (externalEntityId) associada a um documento, o utilizador tem acesso a esse documento.
Por exemplo, suponhamos que criou um conector personalizado para o Jira. Um determinado problema do Jira é acessível a determinados utilizadores do IDP, determinados grupos do IDP e uma função de administrador. Para permitir que esse problema seja acessível a essas pessoas nos resultados da pesquisa, pode criar um arquivo de mapeamento de identidades e mapear os utilizadores e os grupos do IDP para identidades externas específicas do Jira. Associe o arquivo de mapeamento de identidades ao seu arquivo de dados do Jira. Em seguida, crie documentos nos seus repositórios de dados do Jira
aclInfo configurados com os utilizadores do IdP, os grupos do IdP e as identidades externas que
devem ter acesso a esses documentos.
Para atualizar os metadados da ACL com informações sobre as suas identidades externas, use o seguinte formato para especificar as identidades externas e os IDs de utilizadores e grupos associados.
{
"aclInfo": {
"readers": [
{
"principals": [
{
"groupId": "group_1"
},
{
"userId": "user_1"
},
{
"externalEntityId": "external_id1"
}
]
}
]
}
}
Para mais informações sobre a atualização dos metadados da LCA, consulte o artigo Configure uma origem de dados com controlo de acesso.
Faça a gestão dos mapeamentos da identidade
Pode listar as associações de identidades num arquivo de identidades ou expurgar um arquivo de identidades definindo-as através de uma origem inline ou usando uma condição de filtro.
As tarefas de gestão disponíveis para o mapeamento de identidades são:
- Liste os mapeamentos de identidade
- Elimine usando a fonte inline
- Limpe usando uma condição de filtro
Liste mapeamentos da identidade
Para apresentar uma lista de mapeamentos de identidades, execute o seguinte comando através do 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 o seguinte:
PROJECT_ID: o ID do seu projeto.PAGE_SIZE: número máximo de lojas de mapeamento de identidades a devolver. Se não for especificado, a predefinição é 100. O valor máximo permitido é 1000. Os valores superiores a 1000 são forçados a 1000.PAGE_TOKEN: um token de página, recebido de uma chamadaListIdentityMappingStoresanterior. Faculte este valor para obter a página seguinte.
Elimine usando a fonte inline
Pode limpar entradas específicas de um armazenamento de mapeamento de identidades fornecendo um ficheiro JSON com as identidades a limpar.
Para limpar as associações de identidades através da origem inline, execute o seguinte comando com 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 o seguinte:
PROJECT_ID: o ID do seu projeto.IDENTITY_MAPPING_STORE_ID: o ID exclusivo da loja de mapeamento de identidade.IDENTITY_MAPPING_STORE_NAME: o nome da loja de mapeamento de identidade.IDENTITY_MAPPINGS_JSON: os mapeamentos da identidade a serem anulados.
Elimine dados através de uma condição de filtro
Pode limpar entradas especificadas de um armazenamento de mapeamento de identidades filtrando entradas por hora de atualização, identidade externa ou todas as entradas.
Para anular associações de identidades através de uma condição de filtro, execute o seguinte comando com 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 o seguinte:
PROJECT_ID: o ID do seu projeto.IDENTITY_MAPPING_STORE_ID: o ID exclusivo da loja de mapeamento de identidade.IDENTITY_MAPPING_STORE_NAME: o nome da loja de mapeamento de identidade.FILTER_CONDITION: um dos seguintes tipos de filtros:- Hora 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,
*
Faça a gestão das lojas de mapeamento de identidades
Pode obter, eliminar, listar e limpar lojas de mapeamento de identidades.
Get identity mapping store
Para obter um arquivo de mapeamento de identidades, execute o seguinte comando com 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 o seguinte:
PROJECT_ID: o ID do seu projeto.IDENTITY_MAPPING_STORE_ID: o ID exclusivo da loja de mapeamento de identidade.IDENTITY_MAPPING_STORE_NAME: o nome da loja de mapeamento de identidade.
Liste lojas de mapeamento de identidade
Para apresentar uma lista de lojas de mapeamento de identidades, execute o seguinte comando através do 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 o seguinte:
PROJECT_ID: o ID do seu projeto.PAGE_SIZE: número máximo de lojas de mapeamento de identidades a devolver. Se não for especificado, a predefinição é 100. O valor máximo permitido é 1000. Os valores superiores a 1000 são forçados a 1000.PAGE_TOKEN: um token de página, recebido de uma chamadaListIdentityMappingStoresanterior. Faculte este valor para obter a página seguinte.
Elimine associações de identidades
Para eliminar uma loja de mapeamento da identidade, esta não pode estar associada a uma loja de dados e não podem existir mapeamentos da identidade na loja de mapeamento da identidade.
Para eliminar um arquivo de mapeamento de identidades, execute o seguinte comando através do 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 o seguinte:
PROJECT_ID: o ID do seu projeto.IDENTITY_MAPPING_STORE_ID: o ID exclusivo da loja de mapeamento de identidade.IDENTITY_MAPPING_STORE_NAME: o nome da loja de mapeamento de identidade.