企业通常使用身份提供方 (IDP) 管理身份（用户和用户群组）。不过，企业自行构建的自定义应用可让客户创建在相应应用内本地定义的新用户群组。这些应用特有的用户群组或辅助用户 ID 称为外部身份。
为什么设置身份映射？
为确保 Google 可以正确实施访问权限控制，请将您的 IDP 身份映射到您计划与 Gemini Enterprise 搭配使用的自定义应用中的任何外部身份。
为了对应用结果应用访问权限控制，Google 会将 IDP 用作可信来源，以确定您的用户可以访问哪些数据。企业通常会将自己的 IdP 关联到其他 SaaS 解决方案，以便员工可以使用一组公司凭证登录并访问所有公司资源。
如果您通过打算连接到应用的自定义应用等应用定义了外部身份，则您的 IDP 就不是访问权限控制的唯一可信来源。
例如，假设“JaneDoe”存在于网域为“example.com”的示例组织中。IDP 中的 ID 定义为“JaneDoe@example.com”。同一用户在自定义应用中的单独 ID 为“JDoe”。IDP 可能不知道此 ID。因此，Gemini Enterprise 不会通过 IDP 接收有关自定义应用 ID 的信息。
在 Gemini Enterprise 中，身份映射存储在您在其中创建并导入映射的身份映射存储区中。如果您打算使用自定义连接器，可以将身份映射存储区绑定到自定义连接器数据存储区，然后使用有关外部身份的信息更新数据存储区的 ACL 元数据。
准备工作
在设置身份映射之前，请先将您的身份提供方关联到 Google Cloud 项目。
准备身份映射条目
准备要导入的身份映射条目。身份映射应采用以下示例中的格式：
{
"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"
}
]
}
例如，以下图表展示了一个用户-群组成员资格示例，其中 Ext 表示外部群组。此图表展示了外部群组与 IDP 用户和群组之间的关系示例。
此用户-群组成员资格图将具有以下映射：
{
"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"
}
]
}
嵌套的身份成员资格（其中的外部身份具有子身份）必须扁平化。
Google 假设连接器会发送外部身份的主 ID。例如，导入群组 ID 而不是群组名称，因为在自定义应用中，群组名称可能会在群组的生命周期内发生更改。
设置身份映射
按照以下过程在 Gemini Enterprise 中设置 IDP 与外部身份之间的身份映射。在以下步骤中，您将创建一个身份映射存储区，并导入您准备的身份映射。如果您打算使用自定义连接器，还需要创建一个绑定到身份映射存储区的新数据存储区。
创建身份映射存储区
第一步是设置身份映射存储区。这是存储所有身份映射的父级资源。
创建身份映射存储区时，系统会自动从您连接到 Gemini Enterprise 项目的 IDP 中提取 IDP 配置。
如需创建身份映射存储区，请使用
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" }'替换以下内容：
PROJECT_ID：您的项目的 ID。IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。例如：test-id-mapping-store。
导入身份映射
创建身份映射存储区后，导入您准备的身份映射条目。您可以使用内嵌来源（选项 1）或从 Cloud Storage（选项 2）导入身份映射。
从 Cloud Storage 导入时，需遵循以下格式和限制：
- 允许的格式：输入文件必须采用 NDJSON (
.ndjson) 或 JSON Lines (.jsonl) 格式，其中每行表示一个身份映射条目。 - 文件大小限制：每个文件的大小不应超过 2 GB。
- 身份映射数量限制：您可以在一次导入操作中导入最多
500,000个外部身份映射。 - 文件数量限制：您可以在
inputUris列表中指定最多2,000个文件。如果您使用通配符，则此限制适用于通配符展开后的文件总数。
方法 1：使用内嵌来源进行导入
如需使用内嵌来源导入身份映射，请使用
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://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \ -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'替换以下内容：
PROJECT_ID：您的项目的 ID。ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：us（表示美国多区域）eu（表示欧盟多区域）global（表示全球位置）
LOCATION：数据存储区的多区域：global、us或euIDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。IDENTITY_MAPPINGS_JSON：采用 JSON 格式的准备好的身份映射。
如果您打算构建自定义连接器并使用外部身份，请参阅将自定义数据存储区绑定到身份映射存储区。否则，请跳至更新 ACL 元数据。
方法 2：从 Cloud Storage 导入
如需从 Cloud Storage 导入身份映射，请使用
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://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" }'替换以下内容：
PROJECT_ID：您的项目的 ID。ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：us（表示美国多区域）eu（表示欧盟多区域）global（表示全球位置）
LOCATION：数据存储区的多区域：global、us或euIDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。BUCKET_NAME：Cloud Storage 存储桶的名称。FILE_PATH：Cloud Storage 中身份映射文件的路径。ERROR_DIR：Cloud Storage 中将存储错误日志的目录。
如果您打算构建自定义连接器并使用外部身份，请参阅将自定义数据存储区绑定到身份映射存储区。否则，请跳至更新 ACL 元数据。
将自定义数据存储区绑定到身份映射存储区
只有在构建自定义连接器时才需要执行此程序。如果您不构建自定义连接器，请跳过此步骤。
对于自定义连接器，身份映射存储区需要绑定到数据存储区，然后才能将外部身份与其文档相关联。此字段只能在创建数据存储区期间设置。
如需将数据存储区绑定到身份映射存储区，请在创建数据存储区期间使用
Datastores.create方法指定identity_mapping_store。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" }'替换以下内容：
PROJECT_ID：您的项目的 ID。DATA_STORE_ID：您要创建的数据存储区的 ID。此 ID 只能包含小写字母、数字、下划线和连字符。IDENTITY_MAPPING_STORE_NAME：身份映射存储区的完整资源名称。例如：projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store。 创建数据存储区后，此名称将无法更新。
添加 ACL 元数据
在文档的 AclInfo 对象中添加 ACL 元数据。
当用户发送搜索请求并提取 ACL 元数据包含外部身份的文档时，系统会评估这些外部身份。
如果用户的身份（groupID 或 userID）映射到与文档关联的外部身份 (externalEntityId)，则用户可以访问该文档。
例如，假设您已为 Jira 创建了一个自定义连接器。特定 IDP 用户、特定 IDP 群组和管理员角色可以访问给定的 Jira 问题。为了让这些人能够在搜索结果中看到该问题，您可以创建身份映射存储区，并将 IDP 用户和群组映射到 Jira 特定的外部身份。将身份映射存储区绑定到您的 Jira 数据存储区。然后，在 Jira 数据存储区中创建文档，其中 aclInfo 配置有应有权访问这些文档的 IDP 用户、IDP 群组和外部身份。
如需使用有关外部身份的信息更新 ACL 元数据，请使用以下格式指定外部身份以及关联的用户和群组 ID。
{
"aclInfo": {
"readers": [
{
"principals": [
{
"groupId": "group_1"
},
{
"userId": "user_1"
},
{
"externalEntityId": "external_id1"
}
]
}
]
}
}
如需详细了解如何更新 ACL 元数据，请参阅配置具有访问权限控制的数据源。
管理身份映射
您可以列出身份存储区中的身份映射，也可以通过内嵌来源或使用过滤条件来定义身份映射，从而完全清除身份存储区。
身份映射可用的管理任务包括：
列出身份映射
如需列出身份映射，请使用
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"替换以下内容：
PROJECT_ID：您的项目的 ID。PAGE_SIZE：要返回的身份映射存储区的数量上限。如果未指定，则默认为 100。允许的最大值为 1,000。高于 1,000 的值会强制转换为 1,000。PAGE_TOKEN：从之前的ListIdentityMappingStores调用接收的页面令牌。利用其进行后续页面检索。
使用内嵌来源进行完全清除
您可以提供一个 JSON 文件，其中包含要完全清除的身份，从而从身份映射存储区中完全清除指定的条目。
如需使用内嵌来源完全清除身份映射，请使用
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}'替换以下内容：
PROJECT_ID：您的项目的 ID。IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。IDENTITY_MAPPING_STORE_NAME：身份映射存储区名称。IDENTITY_MAPPINGS_JSON：要完全清除的身份映射。
使用过滤条件进行完全清除
您可以按更新时间、外部身份或所有条目过滤条目，从而完全清除身份映射存储区中指定的条目。
如需使用过滤条件完全清除身份映射，请使用
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"}'替换以下内容：
PROJECT_ID：您的项目的 ID。IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。IDENTITY_MAPPING_STORE_NAME：身份映射存储区名称。FILTER_CONDITION：以下过滤条件类型之一：- 更新时间。例如
update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z">。 - 外部身份。例如
external_id = "id1"。 - 所有身份映射。例如
*。
管理身份映射存储区
您可以获取、删除、列出和完全清除身份映射存储区。
获取身份映射存储区
如需获取身份映射存储区，请使用
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"替换以下内容：
PROJECT_ID：您的项目的 ID。IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。IDENTITY_MAPPING_STORE_NAME：身份映射存储区名称。
列出身份映射存储区
如需列出身份映射存储区，请使用
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"替换以下内容：
PROJECT_ID：您的项目的 ID。PAGE_SIZE：要返回的身份映射存储区的数量上限。如果未指定，则默认为 100。允许的最大值为 1,000。高于 1,000 的值会强制转换为 1,000。PAGE_TOKEN：从之前的ListIdentityMappingStores调用接收的页面令牌。利用其进行后续页面检索。
删除身份映射存储区
如需删除身份映射存储区，该存储区不得绑定到数据存储区，并且身份映射存储区中不得存在任何身份映射。
如需删除身份映射存储区，请使用
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"替换以下内容：
PROJECT_ID：您的项目的 ID。IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。IDENTITY_MAPPING_STORE_NAME：身份映射存储区名称。