本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 將 IdP 屬性映射至設定檔和字符 身分提供者 (IdP) 服務，包括 Amazon Cognito，通常可以記錄使用者的詳細資訊。您可能想知道他們服務的公司、如何聯絡他們，以及其他識別資訊。但是，這些屬性採用的格式在提供者之間有差異。例如，使用使用者集區設定來自三個不同廠商的三個 IdPs，並檢查每個廠商的範例 SAML 聲明、ID 字符或`userInfo`承載。一個 會將使用者的電子郵件地址表示為 `email`，另一個 表示為 `emailaddress`，第三個 表示為 `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`。 將 IdPs 與使用者集區整合的主要優點是能夠將各種屬性名稱映射到具有一致、可預測、共用屬性名稱的單一 OIDC 字符結構描述。如此一來，您的開發人員就不需要維護邏輯來處理各種複雜的單一登入事件。此格式合併是屬性映射。使用者集區屬性映射會將 IdP 屬性名稱指派給對應的使用者集區屬性名稱。例如，您可以將使用者集區設定為將`emailaddress`宣告的值寫入標準使用者集區屬性 `email`。 每個使用者集區 IdP 都有單獨的屬性映射結構描述。若要為您的 IdP 指定屬性映射，請在 Amazon Cognito 主控台、 AWS SDK 或使用者集區 REST API 中設定使用者集區身分提供者。 ## 對應的須知事項 開始設定使用者屬性映射之前，請檢閱下列重要詳細資訊。 + 聯合身分使用者登入您的應用程式時，使用者集區所需的每個使用者集區屬性都必須有對應。例如，如果您的使用者集區需要 `email` 屬性進行註冊，請將此屬性對應至 IdP 中的同等屬性。 + 對應的電子郵件地址預設未經驗證。您無法使用單次代碼驗證對應的電子郵件地址。相反地，請對應 IdP 的屬性以取得驗證狀態。例如，Google 和大多數 OIDC 供應商都包含 `email_verified` 屬性。 + 您可以將身分提供者 (IdP) 權杖映射至您的使用者集區中的自訂屬性。社交提供者會顯示存取權仗，OIDC 提供者則會顯示存取和 ID 權仗。若要映射權杖，請新增長度上限為 2,048 個字元的自訂屬性，授予您的應用程式用戶端寫入屬性的權限，以及將 `access_token` 或 `id_token` 從 IdP 映射至自訂屬性。 + 對於每個映射的使用者集區屬性，值的長度上限 2,048 個字元必須足夠容納 Amazon Cognito 從 IdP 取得的值。否則，Amazon Cognito​ 會在使用者登入至您的應用程式時報告錯誤。權杖長度超過 2,048 個字元時，Amazon Cognito 不支援將 IdP 權杖映射至自訂屬性。 + Amazon Cognito 會從聯合身分 IdP 傳遞的特定宣告衍生聯合身分使用者設定檔中的`username`屬性，如下表所示。Amazon Cognito 將此屬性值加上 IdP 的名稱，例如 `MyOIDCIdP_[sub]`。當您希望聯合身分使用者擁有與外部使用者目錄中的屬性完全相符的屬性時，請將該屬性對應至 等 Amazon Cognito 登入屬性`preferred_username`。 [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/cognito/latest/developerguide/cognito-user-pools-specifying-attribute-mapping.html) + 當使用者集區[不區分大小寫](user-pool-case-sensitivity.md)時，Amazon Cognito 會以聯合身分使用者自動產生的使用者名稱將使用者名稱來源屬性轉換為小寫。以下是區分大小寫的使用者集區的範例使用者名稱：`MySAML_TestUser@example.com`。以下是*不區分*大小寫的使用者集區的相同使用者名稱：`MySAML_testuser@example.com`。 在不區分大小寫的使用者集區中，處理使用者名稱的 Lambda 觸發程序必須考慮對使用者名稱來源屬性的任何混合大小寫宣告進行此修改。若要將您的 IdP 連結至與目前使用者集區具有不同區分大小寫設定的使用者集區，請建立新的使用者集區。 + Amazon Cognito 必須在使用者登入至您的應用程式時更新您已對應的使用者集區屬性。使用者透過 IdP 登入時，Amazon Cognito 會使用 IdP 的最新資訊，更新已對應屬性。Amazon Cognito 只會在其值變更時更新映射的屬性。為確保 ​Amazon Cognito 可更新屬性，請確認下列要求： + 從 IdP 映射的所有使用者集區自訂屬性都必須是*可變的*。您隨時都可以更新可變的自訂屬性。相比之下，當您第一次建立使用者描述檔時，您只能為使用者的*不可變*自訂屬性設定一個值。若要在 Amazon Cognito 主控台中建立可變自訂屬性，請在**註冊**功能表中選取**新增自訂屬性**時，為您新增的屬性啟用**可變**核取方塊。或者，若您使用 [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API 操作來建立使用者集區，可將每個屬性的 `Mutable` 參數設為 `true`。如果您的 IdP 傳送對應不可變屬性的值，Amazon Cognito 會傳回錯誤且登入失敗。 + 在應用程式的應用程式用戶端設定中，對應的屬性必須為*可寫入*。您可以在 Amazon Cognito 主控台的 **App clients (應用程式用戶端)** 頁面中，設定哪些屬性為可寫入。或者，若您使用 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html)​ API 操作來建立應用程式用戶端，您可以將這些屬性新增至 `WriteAttributes`​ 陣列。如果您的 IdP 傳送映射不可寫入屬性的值，Amazon Cognito 不會設定屬性值並繼續驗證。 + 當 IdP 屬性包含多個值時，Amazon Cognito 會將所有值扁平化為以方括號字元 `[`和 括住的單一逗號分隔字串`]`。Amazon Cognito URL 表單編碼包含非英數字元的值`-`，但 `.`、`*`、 和 除外`_`。您必須先將個別值解碼並剖析，才能在應用程式中使用。 + 除非登入或管理動作變更，否則目的地屬性會保留屬性映射規則指派給它的任何值。當來源屬性不再以提供者字符或 SAML 聲明傳送時，Amazon Cognito 不會從使用者中移除屬性。下列動作會從聯合身分使用者的使用者集區設定檔中移除屬性的值： 1. IdP 會傳送來源屬性的空白值，而映射規則會將空白值套用至目的地屬性。 1. 您可以使用 [DeleteUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUserAttributes.html) 或 [AdminDeleteUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDeleteUserAttributes.html) 請求清除映射屬性的值。 ## 為您的使用者集區指定身分提供者屬性對應 (AWS 管理主控台) 您可以使用 AWS 管理主控台 來指定使用者集區的 IdP 屬性映射。 **注意** Amazon Cognito 只有在傳入字符中存在宣告時，才會將傳入宣告對應至使用者集區屬性。如果傳入權杖中不再存在先前對應的宣告，則不會刪除或變更該要求。如果您的應用程式需要對應已刪除的要求，您可以使用預先驗證 Lambda 觸發程序以在身分驗證期間刪除自訂屬性，並允許這些屬性從傳入字符重新填入。 **指定社交 IdP 屬性對應** 1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)。如果出現提示，請輸入您的 AWS 登入資料。 1. 在導覽窗格中，選擇 **User Pools** (使用者集區)，然後選擇您要編輯的使用者集區。 1. 選擇**社交和外部供應商**選單。 1. 選擇 **Add an identity provider** (新增身分提供者)，或選擇您已設定的 **Facebook**、**Google**、**Amazon** 或者 **Apple** IdP。找到 **Attribute mapping** (屬性對應)，然後選擇 **Edit** (編輯)。 如需有關新增社交 IdP 的詳細資訊，請參閱[搭配使用者集區使用社交身分提供者](cognito-user-pools-social-idp.md)。 1. 針對您需要對應的每個屬性，完成下列步驟： 1. 從 **User pool attribute** (使用者集區屬性) 欄選取屬性。這是指派給您使用者集區中使用者描述檔的屬性。自訂屬性會列在標準屬性之後。 1. 從 **{{}} attribute** ( 屬性) 欄選取屬性。這是從供應商目錄傳遞的屬性。來自社交供應商的已知屬性會在下拉式清單中提供。 1. 若要在 IdP 和 Amazon Cognito 之間映射其他屬性，請選擇 **Add another attribute** (新增另一個屬性)。 1. 選擇**儲存變更**。 **指定 SAML 供應商屬性對應** 1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)。如果出現提示，請輸入您的 AWS 登入資料。 1. 在導覽窗格中，選擇 **User Pools** (使用者集區)，然後選擇您要編輯的使用者集區。 1. 選擇**社交和外部供應商**選單。 1. 選擇 **Add an identity provider** (新增身分提供者)，或選擇您已設定的 SAML IdP。找到 **Attribute mapping** (屬性對應)，然後選擇 **Edit** (編輯)。如需有關新增 SAML IdP 的詳細資訊，請參閱[搭配使用者集區使用 SAML 身分提供者](cognito-user-pools-saml-idp.md)。 1. 針對您需要對應的每個屬性，完成下列步驟： 1. 從 **User pool attribute** (使用者集區屬性) 欄選取屬性。這是指派給您使用者集區中使用者描述檔的屬性。自訂屬性會列在標準屬性之後。 1. 從 **SAML attribute** (SAML 屬性) 欄選取屬性。這是從供應商目錄傳遞的屬性。 您的 IdP 可能會提供範例 SAML 聲明以供參考。有些 IdP 會使用簡單的名稱，例如 `email`，有些則會使用類似以下的 URL 格式屬性名稱： ``` http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ``` 1. 若要在 IdP 和 Amazon Cognito 之間對應其他屬性，請選擇 **Add another attribute** (新增另一個屬性)。 1. 選擇**儲存變更**。 ## 為您的使用者集區 (AWS CLI 和 AWS API) 指定身分提供者屬性映射 [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) 或 [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) 的下列請求內文`phone_number`會依該順序將 SAML 提供者 "MyIdP" 屬性 `emailaddress`、 `birthdate`和 映射`phone`至使用者集區屬性 `birthdate`、 `email`和 。這是 SAML 2.0 供應商的完整請求內文，您的請求內文會根據 IdP 類型和特定詳細資訊而有所不同。屬性映射位於 `AttributeMapping` 參數中。 ``` { "AttributeMapping": { "email" : "emailaddress", "birthdate" : "birthdate", "phone_number" : "phone" }, "IdpIdentifiers": [ "IdP1", "pdxsaml" ], "ProviderDetails": { "IDPInit": "true", "IDPSignout": "true", "EncryptedResponses" : "true", "MetadataURL": "https://auth.example.com/sso/saml/metadata", "RequestSigningAlgorithm": "rsa-sha256" }, "ProviderName": "MyIdP", "ProviderType": "SAML", "UserPoolId": "us-west-2_EXAMPLE" } ``` 使用下列命令來為您的使用者集區指定 IdP 屬性對應。 **在建立供應商時指定屬性對應** + AWS CLI: `aws cognito-idp create-identity-provider` 使用中繼資料檔案的範例：`aws cognito-idp create-identity-provider --user-pool-id {{}} --provider-name=SAML_provider_1 --provider-type SAML --provider-details file:///details.json --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` 其中 `details.json` 包含： ``` { "MetadataFile": "{{}}" } ``` **注意** 如果 {{}} 包含任何引號 (`"`)，則必須將其逸出 (`\"`)。 中繼資料 URL 的範例： ``` aws cognito-idp create-identity-provider \ --user-pool-id {{us-east-1_EXAMPLE}} \ --provider-name=SAML_provider_1 \ --provider-type SAML \ --provider-details MetadataURL={{https://myidp.example.com/saml/metadata}} \ --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ``` + API/SDK：[CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) **為現有的 IdP 指定屬性對應** + AWS CLI: `aws cognito-idp update-identity-provider` 範例：`aws cognito-idp update-identity-provider --user-pool-id {{}} --provider-name {{}} --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` + API/SDK：[UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) **取得特定 IdP 的屬性對應相關資訊** + AWS CLI: `aws cognito-idp describe-identity-provider` 範例：`aws cognito-idp describe-identity-provider --user-pool-id {{}} --provider-name {{}}` + API/SDK：[DescribeIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeIdentityProvider.html)