此页面由 Cloud Translation API 翻译。

映射外部身份

企业通常使用身份提供方 (IDP) 管理身份（用户和用户群组）。不过，企业自行构建的自定义应用可让客户创建在相应应用内本地定义的新用户群组。这些特定于应用的用户群组或辅助用户 ID 称为外部身份。

为什么要设置身份映射？

为确保 Google 可以正确强制执行访问权限控制，请将您的 IDP 身份映射到您计划与 Gemini Enterprise 搭配使用的任何自定义应用的外部身份。

为了对应用结果应用访问权限控制，Google 会将 IDP 用作事实来源，以确定您的用户可以访问哪些数据。企业通常会将自己的 IdP 连接到其他 SaaS 解决方案，以便员工可以使用一套公司凭据登录并访问所有公司资源。

如果您通过计划连接到应用的自定义应用等应用定义了外部身份，那么您的 IDP 就不是访问权限控制的唯一可靠来源。

例如，假设“JaneDoe”存在于网域为“example.com”的“Example Organization”中。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 用户和群组之间的关系示例。

外部身份与 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。

命令和结果示例

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

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
  "idpConfig": {
    "idpType": "GSUITE"
  }
}

导入身份映射

创建身份映射存储区后，导入您准备的身份映射条目。

如需导入身份映射，请使用 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}'

替换以下内容：

PROJECT_ID：您的项目的 ID。
IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。
IDENTITY_MAPPINGS_JSON：采用 JSON 格式的准备好的身份映射。

命令和结果示例

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: example-project" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store:importIdentityMappings" \
-d '{"inline_source" : { identity_mapping_entries: { external_identity: "external_id_1", user_id: "testuser1@example.com" } , identity_mapping_entries: { external_identity: "external_id_2", user_id: "testuser2@example.com" }, identity_mapping_entries: { external_identity: "external_id2", group_id: "testgroup1@example.com" } }}'

{
  "name": "projects/862721868538/locations/global/identityMappingStores/test-id-mapping-store/operations/import-identity-mappings-14869487418543288420",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.IdentityMappingEntryOperationMetadata",
    "successCount": "2",
    "failureCount": "1",
    "totalCount": "3"
  },
  "done": true
}

接下来，如果您计划构建自定义连接器并使用外部身份，请前往将自定义数据存储区绑定到身份映射存储区。否则，请跳至更新 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。允许的最大值为 1000。高于 1000 的值会强制转换为 1000。
PAGE_TOKEN：从之前的 ListIdentityMappingStores 调用接收的页面令牌。利用其进行后续页面检索。

命令和结果示例

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: example-project" \
https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store:listIdentityMappings

{
  "identityMappingEntries": [
    {
      "externalIdentity": "external_group2",
      "groupId": "example-group@google.com"
    },
    {
      "externalIdentity": "external_id_1",
      "userId": "example-user@google.com"
    }
  ],
  "nextPageToken": "gNiNWOiRTMxEWMwATLmNDMh1CO0IjMtADMwATLkRWYkZTZ3YDJawB2h-LEG8ro3XLCLIBZ2YmNz"
}

使用内嵌来源进行清理

您可以提供一个 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"。
所有身份映射。例如 *。

命令和结果示例

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: ucs-ga-fishfood-1" \
"https://discoveryengine.googleapis.com/v1/projects/ucs-ga-fishfood-1/locations/global/identityMappingStores/test-id-mapping-store:purgeIdentityMappings" \
-d '{"identity_mapping_store":"test-id-mapping-store", "filter": "*"}'

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store/operations/purge-identity-mappings-200445172458892000",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.IdentityMappingEntryOperationMetadata"
  }
}

管理身份映射存储区

您可以获取、删除、列出和清除身份映射存储区。

获取身份映射存储区

如需获取身份映射存储区，请使用 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：身份映射存储区名称。

命令和结果示例

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

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
  "idpConfig": {
    "idpType": "GSUITE"
  }
}

列出身份映射存储区

如需列出身份映射存储区，请使用 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。允许的最大值为 1000。高于 1000 的值会强制转换为 1000。
PAGE_TOKEN：从之前的 ListIdentityMappingStores 调用接收的页面令牌。利用其进行后续页面检索。

命令和结果示例

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: ucs-ga-fishfood-1" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores"

{
  "identityMappingStores": [
    {
      "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
      "idpConfig": {
        "idpType": "GSUITE"
      }
    }
  ]
}

删除身份映射存储区

如需删除身份映射存储区，该存储区不得绑定到任何数据存储区，并且其中不得包含任何身份映射。

如需删除身份映射存储区，请使用 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：身份映射存储区名称。

映射外部身份 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

为什么要设置身份映射？

准备工作

准备身份映射条目

设置身份映射

创建身份映射存储区

命令和结果示例

导入身份映射

命令和结果示例

将自定义数据存储区绑定到身份映射存储区

添加 ACL 元数据

管理身份映射

列出身份映射

命令和结果示例

使用内嵌来源进行清理

使用过滤条件进行完全清除

命令和结果示例

管理身份映射存储区

获取身份映射存储区

命令和结果示例

列出身份映射存储区

命令和结果示例

删除身份映射存储区

映射外部身份