對應的須知事項為您的使用者集區指定身分提供者屬性對應 (AWS Management Console)為您的使用者集區 (AWS CLI 和 AWS API) 指定身分提供者屬性映射

將 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 軟體開發套件或使用者集區 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。

身分提供者	`username` 資源屬性
Facebook	`id`
Google	`sub`
登入 Amazon	`user_id`
使用 Apple 登入	`sub`
SAML 供應商	`NameID`
OpenID Connect (OIDC) 供應商	`sub`

當使用者集區不區分大小寫時，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 API 操作來建立使用者集區，可將每個屬性的 Mutable 參數設為 true。如果您的 IdP 傳送對應不可變屬性的值，Amazon Cognito 會傳回錯誤且登入失敗。
- 在應用程式的應用程式用戶端設定中，對應的屬性必須為可寫入。您可以在 Amazon Cognito 主控台的 App clients (應用程式用戶端) 頁面中，設定哪些屬性為可寫入。或者，若您使用 CreateUserPoolClient API 操作來建立應用程式用戶端，您可以將這些屬性新增至 WriteAttributes 陣列。如果您的 IdP 傳送映射的不可寫入屬性的值，Amazon Cognito 不會設定屬性值，並繼續驗證。
當 IdP 屬性包含多個值時，Amazon Cognito 會將所有值扁平化為單一逗號分隔字串，而 URL 形式會編碼包含非英數字元的值（不包括 ‘.’、’-’、‘*’ 和 ‘_’)。您必須先將個別值解碼並剖析，才能在應用程式中使用。

為您的使用者集區指定身分提供者屬性對應 (AWS Management Console)

您可以使用 AWS Management Console 來指定使用者集區的 IdP 屬性映射。

注意

Amazon Cognito 只有在傳入字符中存在宣告時，才會將傳入宣告對應至使用者集區屬性。如果傳入權杖中不再存在先前對應的宣告，則不會刪除或變更該要求。如果您的應用程式需要對應已刪除的要求，您可以使用預先驗證 Lambda 觸發程序以在身分驗證期間刪除自訂屬性，並允許這些屬性從傳入字符重新填入。

指定社交 IdP 屬性對應

登入 Amazon Cognito 主控台。如果出現提示，請輸入您的 AWS 登入資料。
在導覽窗格中，選擇 User Pools (使用者集區)，然後選擇您要編輯的使用者集區。
選擇社交和外部供應商選單。
選擇 Add an identity provider (新增身分提供者)，或選擇您已設定的 Facebook、Google、Amazon 或者 Apple IdP。找到 Attribute mapping (屬性對應)，然後選擇 Edit (編輯)。

如需有關新增社交 IdP 的詳細資訊，請參閱搭配使用者集區使用社交身分提供者。
針對您需要對應的每個屬性，完成下列步驟：
1. 從 User pool attribute (使用者集區屬性) 欄選取屬性。這是指派給您使用者集區中使用者描述檔的屬性。自訂屬性會列在標準屬性之後。
2. 從 <provider> attribute (<provider> 屬性) 欄選取屬性。這是從供應商目錄傳遞的屬性。來自社交供應商的已知屬性會在下拉式清單中提供。
3. 若要在 IdP 和 Amazon Cognito 之間映射其他屬性，請選擇 Add another attribute (新增另一個屬性)。
選擇 Save changes (儲存變更)。

指定 SAML 供應商屬性對應

登入 Amazon Cognito 主控台。如果出現提示，請輸入您的 AWS 登入資料。
在導覽窗格中，選擇 User Pools (使用者集區)，然後選擇您要編輯的使用者集區。
選擇社交和外部供應商選單。
選擇 Add an identity provider (新增身分提供者)，或選擇您已設定的 SAML IdP。找到 Attribute mapping (屬性對應)，然後選擇 Edit (編輯)。如需有關新增 SAML IdP 的詳細資訊，請參閱搭配使用者集區使用 SAML 身分提供者。
針對您需要對應的每個屬性，完成下列步驟：
1. 從 User pool attribute (使用者集區屬性) 欄選取屬性。這是指派給您使用者集區中使用者描述檔的屬性。自訂屬性會列在標準屬性之後。
2. 從 SAML attribute (SAML 屬性) 欄選取屬性。這是從供應商目錄傳遞的屬性。
  
  您的 IdP 可能會提供範例 SAML 聲明以供參考。有些 IdP 會使用簡單的名稱，例如 email，有些則會使用類似以下的 URL 格式屬性名稱：
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```
3. 若要在 IdP 和 Amazon Cognito 之間對應其他屬性，請選擇 Add another attribute (新增另一個屬性)。
選擇 Save changes (儲存變更)。

為您的使用者集區 (AWS CLI 和 AWS API) 指定身分提供者屬性映射

下列 CreateIdentityProvider 或 UpdateIdentityProvider 的請求內文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 <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": "<SAML metadata XML>"
}
```
注意
如果 <SAML metadata XML> 包含任何引號 (")，則必須將其逸出 (\")。

中繼資料 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

為現有的 IdP 指定屬性對應

AWS CLI: aws cognito-idp update-identity-provider

範例：aws cognito-idp update-identity-provider --user-pool-id <user_pool_id> --provider-name <provider_name> --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
API/SDK：UpdateIdentityProvider

取得特定 IdP 的屬性對應相關資訊

AWS CLI: aws cognito-idp describe-identity-provider

範例：aws cognito-idp describe-identity-provider --user-pool-id <user_pool_id> --provider-name <provider_name>
API/SDK： DescribeIdentityProvider

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

OIDC 使用者集區 IdP 身分驗證流程

連結聯合身分使用者