企業通常會使用識別資訊提供者 (IDP) 管理身分 (使用者和使用者群組)。不過，企業內部建構的自訂應用程式，可讓客戶建立在該應用程式中定義的新使用者群組。這些應用程式專屬的使用者群組或次要使用者 ID 稱為「外部身分」。
為什麼要設定識別資訊對應？
為確保 Google 能正確執行存取控管，請將 IDP 身分對應至您打算與 Gemini Enterprise 搭配使用的自訂應用程式中的任何外部身分。
為對應用程式搜尋結果套用存取控管，Google 會以 IDP 為可靠資料來源，判斷使用者可存取哪些資料。企業通常會將 IDP 連結至其他 SaaS 解決方案，讓員工使用一組公司憑證，即可登入及存取所有公司資源。
如果您透過打算連結至應用程式的應用程式 (例如自訂應用程式) 定義外部身分，則 IDP 不是存取控管的唯一可靠資料來源。
舉例來說，假設「JaneDoe」存在於 Example Organization 中，網域為「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 bucket 的名稱。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 建立了自訂連接器。特定 Jira 問題可由特定 IDP 使用者、特定 IDP 群組和管理員角色存取。如要允許這些使用者在搜尋結果中存取該問題，您可以建立身分對應儲存庫，並將 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呼叫的網頁權杖。提供此項目即可擷取後續網頁。
使用內嵌來源清除
您可以提供要清除的身分 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。最大允許值為 1000。如果值大於 1000，則會強制轉型為 1000。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：身分對應儲存庫名稱。