如何排查用户在 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 编码。在发送 SAMLResponse 值进行 base64 解码之前，执行 URL 解码。

解决无效的 SAML 响应错误

“收到的 SAML 响应无效： 无效的用户属性:<attribute\ _name>： 该属性是必选的。”

当用户群体配置了必选属性但 IdP 没有传递对必选属性的声明时，会出现此错误。必选属性的属性映射不可用时，也会出现此错误。

请按照以下步骤解决错误：

1.   打开 Amazon Cognito 控制台。

2.   选择您的用户群体。

3.   查看有关用户群体的信息。注意在注册体验下配置的必选属性。

4.    在浏览器中检索和查看 SAML 响应。

5.   检查 IdP 是否传递了响应的 AttributeStatement 字段中的所有必选属性声明。如果 IdP 未发送 SAML 响应中的所有必选属性，请查看您的 IdP 的属性映射配置。确保将您的 IdP 配置为发送必选属性的正确映射。

注意： 您的 IdP 可能会提供示例 SAML 断言以供参考。您可以查看断言，获取有关 IdP 映射属性的更多详细信息。有些 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 属性设置为不可变（**“可变”：“false”），则会出现此错误。**创建用户群体后，您无法更改属性的可变性设置。要解决此错误，您需要删除将 SAML 属性映射到不可变属性的属性映射规则。

请按照以下步骤解决错误：

1.   运行以下 AWS 命令行接口 (AWS CLI) 命令并记下输出中返回的属性。输出中返回的所有属性都是不可变的。

**注意：****<userpool\ _id> ** 替换为您的用户群体 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: xxxxxxxxx 上使用。”
-或-
“收到的 SAML 响应无效： 找不到标识符为 “urn: amazon: cognito: sp: xxxxxxx” 的应用程序。“

**注意：**错误消息因 IdP 而异。

在 IdP 上错误配置实体 ID 时，会出现此错误。使用另一个用户池的 URN 作为实体 ID 时，也会出现此错误。

请按照以下步骤解决错误：

1.   打开 Amazon Cognito 控制台。

2.   选择用户群体，然后记下您的用户池 ID。

3.   转到 IdP 的 SAML 应用程序设置，然后按以下格式配置实体 ID：

**注意：****<user\ _pool\ _id> ** 替换为您的 Amazon Cognito 用户群体 ID。

urn:amazon:cognito:sp:<user_pool_id>

“请求的页面出现错误。“

此错误发生在 Amazon Cognito 托管用户界面页面上。如果此错误消息没有任何其他错误语句，则表示您的应用程序的断言消费者服务 (ACS) URL 配置不正确。您的 IdP 使用 ACS 网址向 Amazon Cognito 发送 SAML 响应。ACS 网址遵循以下格式：

**注意：****<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 无效。”

出现此错误的原因如下：

• 向 Amazon Cognito 发送 SAML 响应时，IdP 将 RelayState 参数设置为空。
• SAML 请求中的 ACS 网址与您的 IdP 应用程序中配置的 ACS 网址不同。

在向您的 IdP 转发身份验证请求时， Cognito 会生成 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/authority 端点是一个重定向端点，支持两个重定向目标。您在 URL 中包含 identity_provider 或 idp_identifier 参数时，您的用户无缝重定向到 IdP 的登录页面。您可以使用此选项跳过托管界面的默认布局，直接重定向到 IdP 页面。

如果对同一 IdP 应用程序的联合身份验证请求来自不同的用户群体，ACS URL 不同也会发生错误。请按照以下步骤调查并解决错误：

1.   在 Amazon Cognito 进行联合身份验证时，捕获 HTTP 存档 (HAR) 文件。

2.   在浏览器的网络 选项卡上，查找带有 saml?SamlRequest的请求，然后打开请求。

3.   复制请求参数中提供的 SAMLRequest 。

4. 使用您的首选 SAML 解码工具对 SAMLRequest 进行解码。然后，检查 SAMLRequest 中发送的 ACS 网址是否与在 IdP 应用程序上设置的 ACS 网址相同。

SAMLRequest 值不同时，将确认错误。

5.   要解决错误，请检查您的 IdP 配置。确保在应用程序上设置的 ACS 网址与在 SAMLRequest 中发送的 ACS 网址相同。

从不同的用户群体为同一 IdP 应用程序生成联合身份验证请求时，ACS URL 会有所不同。确保从相应的用户群体启动联合身份验证请求。