如何對使用者聯合到 Amazon Cognito 時可能收到的無效 SAML 回應錯誤進行疑難排解？

解決方案

Amazon Cognito 支援透過身分提供者 (IdP) 和 SAML 2.0 進行身分驗證。使用者使用 SAML 聯合到 Amazon Cognito 時可能會遇到一些常見錯誤。

注意： 在整個過程，使用您錯誤情境的使用者屬性取代 <attribute_name>。

檢視 SAML 回應

若要解決常見的 SAML 聯合錯誤，請查看從 IdP 傳送到 Amazon Cognito 使用者集區的 SAML 回應。如需如何擷取和解碼 SAML 回應的指示，請參閱在瀏覽器中檢視 SAML 回應。

注意： SAMLResponse 元素包含 Base64 編碼請求。若承載具有 % 字元，表示該承載除了 Base64 編碼外還進行了 URL 編碼。將其傳送用於 Base64 解碼之前，請先對 SAMLResponse 值執行 URL 解碼。

解決無效 SAML 回應錯誤

「收到無效 SAML 回應： 無效使用者屬性：<attribute_name>： 該屬性為必要項。」

當使用者集區設定必要屬性，但 IdP 並未傳遞必要屬性的宣告時，就會發生此錯誤。當必要屬性無法使用屬性映射時，也會發生此錯誤。

若要解決錯誤，請遵循下列步驟：

1. 開啟 Amazon Cognito 主控台。

2. 選取您的使用者集區。

3. 檢閱使用者集區的相關資訊。請注意註冊體驗下設定的必要屬性。

4. 在瀏覽器中擷取並檢閱 SAML 回應。

5. 檢查該 IdP 是否在回應的 AttributeStatement 欄位傳遞所有必要屬性宣告。如果該 IdP 並未在 SAML 回應中傳送所有必要屬性，請檢閱 IdP 的屬性映射組態。請確認您的 IdP 已設定為傳送必要屬性的正確映射。

注意： 您的 IdP 可能會提供範例 SAML 宣告，以供參考。您可以檢查宣告，以取得有關 IdP 映射屬性的更多詳細資訊。有些 IdP 會針對屬性映射 (例如電子郵件地址) 使用簡單的名稱，而其他則會使用類似於下列範例的 URL 格式屬性名稱：

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

6. 當 SAML 回應包含必要的屬性，但您仍然遇到相同錯誤時，請檢查 Amazon Cognito 屬性映射。當必要屬性缺少映射時，請將映射新增至屬性宣告。如需如何新增屬性映射的指示，請參閱為您的使用者集區指定身分提供者屬性映射。

「收到無效 SAML 回應： 無效使用者屬性：<attribute_name>： 無法刪除必要屬性。」

當在 IdP 中變更必要屬性，使該必要屬性為空值或已刪除時，就會發生此錯誤。當在建立使用者後移除映射時，也會發生此錯誤。

若要解決錯誤，請遵循下列步驟：

1. 開啟 Amazon Cognito 主控台。

2. 選取您的 Amazon Cognito 使用者集區。

3. 檢閱使用者集區的相關資訊。請注意已設定的必要屬性。

4. 在瀏覽器中擷取並檢閱 SAML 回應。

5. 檢查該 IdP 是否在回應的 AttributeStatement 欄位傳遞所有必要屬性宣告。如果該 IdP 並未在 SAML 回應中傳送所有必要屬性，請檢閱 IdP 的屬性映射組態。請確認您的 IdP 已設定為傳送必要屬性的正確映射。

6. 如果在 SAML 回應中傳遞所有必要屬性並具有有效值，請檢查 IdP 屬性映射。請確認所有必要屬性均具備映射。

注意： 當 IdP 的必要屬性為已刪除或變更為空值後，您可能會在聯合請求期間遇到下列錯誤： **「收到無效 SAML 回應： 無效使用者屬性：<attribute_name>： 無法刪除必要屬性。」**當在建立使用者後移除映射時，也會發生此錯誤。若要解決此錯誤，請依照前述步驟確認必要屬性具備映射。然後從您的 IdP 傳遞為必要屬性傳遞正確的值。

「收到無效 SAML 回應： 無效使用者屬性：<attribute_name>： 無法更新屬性。」

當從 IdP 傳遞屬性，但映射的 Amazon Cognito 屬性設定為不可變 ("mutable" : "false") 時，就會發生此錯誤。使用者集區經建立後，您無法變更屬性的可變性設定。若要解決此錯誤，您需要移除將 SAML 屬性映射至不可變屬性的屬性映射規則。

若要解決錯誤，請遵循下列步驟：

1. 執行下列 AWS Command Line Interface (AWS CLI) 命令，並記下輸出中傳回的屬性。輸出中傳回的所有屬性都是不可變的。

注意： 使用您的使用者集區 ID 取代 <userpool_id>。

aws cognito-idp describe-user-pool --user-pool-id <userpool_id> --query 'UserPool.SchemaAttributes[?Mutable==`false`].Name'

注意： 如果您在執行 AWS CLI 命令時收到錯誤訊息，請確認您使用的是最新版本的 AWS CLI。

2. 開啟 Amazon Cognito 主控台。

3. 檢閱您提供者的 SAML 屬性映射。

4. 檢查是否有任何 SAML 屬性映射至命令輸出中傳回的 Amazon Cognito 屬性。如果存在不可變屬性的映射，請刪除該映射。如果您需要映射該 SAML 屬性，請將其映射到任何現有的可變屬性。您也可以建立自訂可變屬性，並將該 SAML 屬性映射至自訂可變屬性。

因為需要對應屬性，所以沒有您可以在現有使用者集區執行並刪除映射的解決方式。您必須使用所需的可變性設定建立新的使用者集區，並將使用者移轉至新的使用者集區。

「收到無效 SAML 回應： SAML 回應簽章無效。」

當 IdP 變更 SAML 簽署憑證時，就會發生此錯誤。若要對此問題進行疑難排解，請檢閱您在聯合到 Amazon Cognito 時收到的 SAML 回應。請注意 X509Certificate 欄位給定的值。將 SAML 回應的 X509Certificate 值與上傳至 Amazon Cognito 用於 IdP 組態的中繼資料 XML 檔案的 X509Certificate 值進行比較。如果兩個值不同，則表示該 IdP 使用的 SAML 簽署憑證已更新。

若要解決錯誤，請遵循下列步驟：

1. 導覽至 IdP 的應用程式設定頁面，然後擷取已更新的中繼資料檔案。

2. 開啟 Amazon Cognito 主控台。

3. 導覽至您的 SAML IdP 組態。

4. 使用已更新的中繼資料檔案取代現有的中繼資料檔案。
   -或-
   如果您的 IdP 透過公有 URL 提供 SAML 中繼資料，請複製該中繼資料文件 URL。貼上該公有 URL，而不是上傳中繼資料檔案。

「收到無效 SAML 回應： SAML 宣吿的對象限制不允許將其用於 urn:amazon:cognito:sp:xxxxxxxx。」
-或-
「收到無效 SAML 回應： 找不到識別符為 'urn:amazon:cognito:sp:xxxxxxxx' 的應用程式。」

注意： 錯誤訊息根據 IdP 而有所不同。

當您在 IdP 上錯誤設定實體 ID 時，就會發生此錯誤。當您將其他使用者集區的 URN 用作實體 ID 時，也會發生此錯誤。

若要解決錯誤，請遵循下列步驟：

1. 開啟 Amazon Cognito 主控台。

2. 選擇使用者集區，然後記下您的使用者集區 ID。

3. 前往該 IdP 的 SAML 應用程式設定，然後以下列格式設定該實體 ID：

注意： 使用您的 Amazon Cognito 使用者集區 ID 取代 <user_pool_id>。

urn:amazon:cognito:sp:<user_pool_id>

「請求頁面發生錯誤。」

這個錯誤會出現在 Amazon Cognito 託管 UI 頁面上。當此錯誤訊息並未伴隨任何其他錯誤陳述式時，表示您應用程式的聲明消費者服務 (ACS) URL 設定不正確。您的 IdP 會使用 ACS URL 將 SAML 回應傳送至 Amazon Cognito。ACS URL 遵循以下格式：

注意： 使用您的使用者集區網域取代 <your_user_pool_domain>。

https://<your_user_pool_domain>/saml2/idpresponse

Amazon Cognito 僅支援端點的 POST 繫結。您的 IdP 必須將 POST 請求的 SAML 回應傳送至該端點。如果您在 IdP 的應用程式上錯誤設定此 URL，您的 IdP 會將 SAML 回應傳送至不正確的端點。這會導致 400 錯誤和聯合失敗。

若要解決錯誤，請遵循下列步驟：

1. 前往您的 IdP 應用程式組態，並使用下列其中一種格式設定該 ACS URL：

Cognito 網域：

https://<your_user_pool_domain>.auth.<region>.amazoncognito.com/saml2/idpresponse

自訂網域：

https://<your_user_pool_domain>/saml2/idpresponse

「請求頁面發生錯誤： 身分提供者的 relayState 無效。」
-或-
「請求頁面發生錯誤： 身分提供者的 samlResponse 或 relayState 無效。」

發生此錯誤的原因如下：

• IdP 在 SAML 回應傳送至 Amazon Cognito 時將 RelayState 參數設定為空值。
• SAML 請求的 ACS URL 與您 IdP 應用程式設定的 ACS URL 不同。

Amazon Cognito 會在將身份驗證請求轉發至您的 IdP 時產生 RelayState 參數。成功驗證後，IdP 必須將此 RelayState 參數傳回至 Amazon Cognito。

在 SAML 聯合期間，使用者集區會代表您的應用程式作為服務提供者。作為服務提供者，Amazon Cognito 僅支援服務提供者啟動的單一登入 (SSO) 流程。不支援 IDP 啟動的流程。當從您的 IdP 啟動聯合請求時，IdP 的必要屬性為已刪除或已變更為空值。聯合失敗是包含先前提到的錯誤訊息的結果。

若要解決此錯誤，請從 Amazon Cognito (而不是 IdP) 啟動聯合請求。若要從 Amazon Cognito 啟動聯合，請執行下列其中一個步驟以啟動身分驗證流程：

• 將使用者重新導向至 /login 端點以進行登入。/login 端點會載入登入頁面，並向使用者顯示用戶端身分驗證選項。當使用者需要檢查不同選項來登入您的應用程式並被重新導向至 IdP 時，請連線至 /login 端點。
• 將請求傳送至 Amazon Cognito 的 /oauth2/authorize 端點。/oauth2/authorize 端點是支援兩個重新導向目的地的重新導向端點。當您在 URL 中包含 identity_provider 或 idp_identifier 參數時，您的使用者會無縫重新導向至 IdP 的登入頁面。您可以使用此選項來跳過託管 UI 的預設配置，並直接重新導向至 IdP 頁面。

當來自不同使用者集區的相同 IdP 應用程式聯合請求的 ACS URL 不同時，也會發生此錯誤。若要進行調查並解決錯誤，請遵循下列步驟：

1. 當您聯合到 Amazon Cognito 時，擷取 HTTP 封存 (HAR) 檔案。

2. 在您瀏覽器的網路索引標籤，尋找具備 saml?SamlRequest 項目的請求，然後開啟該請求。

3. 複製請求參數提供的 SAMLRequest。

4. 使用您偏好的 SAML 解碼工具來解碼 SAMLRequest。然後，檢查傳送至 SAMLRequest 的 ACS URL 是否與您的 IdP 應用程式上設定的 ACS URL 相同。

當兩個 SAMLRequest 值不同時，即確認存在錯誤。

5. 若要解決此錯誤，請檢查您的 IdP 組態。請確認您的應用程式上設定的 ACS URL 與傳送至 SAMLRequest 的 ACS URL 相同。

當從來自不同使用者集區的相同 IdP 應用程式產生聯合請求時，ACS URL 不同。請確認您從正確的使用者集區啟動聯合要求。