如何排查用户在 Amazon Cognito 中进行联合身份验证时收到的 SAML 响应无效错误？

解决方法

查看 SAML 响应

在浏览器中，查看您的身份提供者 (IdP) 发送给 Amazon Cognito 的 SAML 响应。

**注意：**SAMLResponse 元素包含 base64 编码的响应。如果您在有效载荷中看到百分比 (%) 字符，则响应采用 URL 编码和 base64 编码。在这种情况下，对 SAMLResponse 值执行 URL 解码，然后应用 base64 解码。

检查您的属性映射

“The attribute is required”

您会收到以下错误消息：

“Invalid SAML response received: Invalid user attributes: <attribute_name>: The attribute is required”

要解决此问题，请完成以下步骤：

1. 打开 Amazon Cognito 控制台。
2. 在导航窗格中，选择 User pools（用户池），然后选择您的用户池。
3. 在 Sign-up experience（注册体验）下，记下您配置的必填属性。
4. 检查您是否为用户池配置了属性映射。如果您没有映射属性，请指定属性映射。
5. 在浏览器中检索 SAML 响应。
6. 在 AttributeStatement 字段中，验证 IdP 是否包含必填属性。
7. 在您的 IdP 的属性映射配置中，确认您将 IdP 设置为发送具有正确映射的必填属性。

**注意：**您的 IdP 可能会使用简单名称进行属性映射，例如电子邮件地址或 URL 格式。URL 格式的属性名称的示例为 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress。

“Required attribute cannot be deleted”

您会收到以下错误消息：

“Invalid SAML response received: Invalid user attributes: <attribute_name>: Required attribute cannot be deleted”

当 IdP 在创建用户后将必填属性设置为 null、删除必填属性或删除属性映射时，就会出现此错误。

要解决此问题，请映射所有必填属性并配置 IdP 以发送正确的属性值。

有关详细信息，请参阅有关映射的注意事项。

检查不可变的属性

**注意：**如果您在运行 AWS 命令行界面 (AWS CLI) 命令时收到错误，请参阅 AWS CLI 错误故障排除。此外，请确保您使用的是最新版本的 AWS CLI。

您会收到以下错误消息：

“Invalid SAML response received: Invalid user attributes: <attribute_name>: Attribute cannot be updated”

当 IdP 传递映射到不可变的 Amazon Cognito 属性的属性时，就会出现此错误。创建用户池后，无法更改属性的可变性。

要解决此问题，请完成以下步骤：

1. 运行以下 describe-user-pool 命令：

   aws cognito-idp describe-user-pool --user-pool-id USER-POOL-ID --query 'UserPool.SchemaAttributes[?Mutable==`false`].Name'

   **注意：**将 USER-POOL-ID 替换为您的用户池 ID。
2. 在命令的输出中，记下所有不可变的属性。
3. 打开 Amazon Cognito 控制台。
4. 在您的 IdP 的 SAML 属性映射中，检查您的 SAML 属性是否映射到 Amazon Cognito 不可变的属性。如果 SAML 属性映射到不可变的属性，请删除该映射。
   **注意：**如果必须映射 SAML 属性，请将其映射到现有的可变属性。您还可以创建可映射到 SAML 属性的自定义可变属性。

如果您需要映射的属性，请使用正确的可变性设置创建新的用户池，并将用户导入到新的用户池中。

比较您的 SAML 响应与 IdP 元数据 XML 文件的值

您会收到以下错误消息：

“Invalid SAML response received: SAML Response signature is invalid”

当您的 IdP 更新其 SAML 签名证书时，将会出现此错误。此更新会导致您的 SAML 响应与 IdP 元数据 XML 文件中的 X509Certificate 值不匹配。

要解决此问题，请完成以下步骤：

1. 在您的 IdP 的应用程序配置页面下载最新的元数据文件。
   **注意：**如果您的 IdP 通过公共 URL 提供 SAML 元数据，您可以记下元数据文档 URL 并输入公共 URL。
2. 打开 Amazon Cognito 控制台。
3. 在 SAML IdP 的配置设置中，将现有的元数据文件替换为新的元数据文件。

检查实体 ID 和 URN

您会收到以下错误消息之一：

“Invalid SAML response received: Audience restriction in SAML Assertion does not allow it for urn:amazon:cognito:sp:xxxxxxxx”

-或-

“Invalid SAML response received: Application with identifier 'urn:amazon:cognito:sp:xxxxxxxx' was not found”

当您在 IdP 中配置不正确的实体 ID 或使用其他用户池的统一资源名称 (URN) 时，就会出现这些错误。

要解决此问题，请完成以下步骤：

1. 打开 Amazon Cognito 控制台。
2. 在导航窗格中，选择 User pools（用户池），然后选择要为 SAML 集成配置的用户池。
3. 在导航窗格中，选择 Overview（概述），然后记下您的用户池 ID。
4. 在 IdP 的 SAML 应用程序设置中，以 urn:amazon:cognito:sp:USER-POOL-ID 格式配置实体 ID。
   **注意：**将 USER-POOL-ID 替换为您的 Amazon Cognito 用户池 ID。

检查您的 IdP 的断言使用者 (ACS) URL 配置

您会收到以下错误消息：

“An error was encountered with the requested page”

当您错误地配置 IdP 的断言使用者服务 (ACS) URL 时，就会在 Amazon Cognito 托管登录页面上出现此错误。Amazon Cognito 仅支持端点的 POST 绑定。您的 IdP 必须在 POST 请求中向端点发送 SAML 响应。如果您在 IdP 的应用程序上错误配置了 URL，则您的 IdP 将 SAML 响应发送到错误的端点。

要解决此问题，请使用正确的 ACS URL 格式配置 IdP 的应用程序。

默认 Amazon Cognito 用户池域的示例格式为 https://YOUR-USER-POOL-DOMAIN.auth.REGION.amazoncognito.com/saml2/idpresponse。

自定义用户池域的示例格式为 https://YOUR-USER-POOL-DOMAIN/saml2/idpresponse。

**注意：**将 YOUR-USER-POOL-DOMAIN 替换为您的用户池域。

确认您的 IdP 支持的登录类型

您会收到以下错误消息之一：

“An error was encountered with the requested page: Invalid relayState from identity provider”

-或-

“An error was encountered with the requested page: Invalid samlResponse or relayState from identity provider”

这些错误在 IdP 发起的和服务提供商发起的（SP 发起的）SAML 登录流程中都会出现，原因如下：

• IdP 在对 Amazon Cognito 的 SAML 响应中将 RelayState 参数设置为 null。
• 您在不同的用户池中使用了相同的 IdP 应用程序。因此，SAML 请求中的 ACS URL 与您的 IdP 应用程序配置中的 ACS URL 不匹配。

**注意：**对于 SP 发起的 SAML 登录流程，Amazon Cognito 在向您的 IdP 发出的身份验证请求中包含 RelayState 参数。身份验证后，您的 IdP 必须将 RelayState 参数返回给 Amazon Cognito。对于 IdP 发起的 SAML 登录流程，您的 IdP 必须包含 RelayState 参数和 /saml2/idpresponse 端点的 SAML 断言。

要解决 RelayState 问题，请确定您的 SAML IdP 是仅支持 SP 发起的 SAML 登录，还是同时支持 IdP 发起的和 SP 发起的 SAML 登录。

如果您的 IdP 支持 SP 发起的 SAML 登录流程，请从 Amazon Cognito 启动您的身份验证流程以启动联合身份验证请求。您可以使用将用户重定向到登录端点的 /login 托管登录端点。或者，使用 /oauth2/authorize 重定向和身份验证端点。

如果您的 IdP 支持 IdP 发起的 SAML 登录流程，请使用 RelayState 参数以 identity_provider=ID-PROVIDER-NAME&client_id=CLIENT-ID&redirect_uri=CALLBACK-URL&response_type=code&scope=openid+email+phone 格式配置您的 SAML IdP。

**注意：**将 ID-PROVIDER-NAME 替换为您的 SAML IdP 的名称。此外，将 CLIENT-ID 替换为用户池的应用程序客户端 ID，并将 CALLBACK-URL 替换为应用程序客户端 ID 的回调 URL。

要解决 ACS URL 问题，请完成以下步骤：

1. 创建 HTTP 存档 (HAR) 文件。
2. 在浏览器的 Network（网络）选项卡中，找到带有 saml?SamlRequest 条目的请求。
3. 记下请求参数中的 SAMLRequest。
4. 使用您的首选 SAML 解码工具对 SAMLRequest 进行解码。
5. 将解码请求中的 ACS URL 与 IdP 配置中的 ACS URL 进行比较。

如果 URL 不同，请更新您的 IdP 配置以匹配 SAMLRequest 中的 ACS URL。然后，从正确的用户池启动联合身份验证请求。