# 排查 SAML 与 IAM 联合身份验证的问题
<a name="troubleshoot_saml"></a>

使用此处的信息可帮助您诊断和修复在将 SAML 2.0 与 Amazon Identity and Access Management 联合使用时可能遇到的问题。

**Topics**
+ [错误：您的请求包含无效的 SAML 响应。要注销，请单击此处。](#troubleshoot_saml_invalid-response)
+ [错误：AuthnResponse 中需要 RoleSessionName（服务：AWSSecurityTokenService；状态代码：400；错误代码：InvalidIdentityToken）](#troubleshoot_saml_missing-rolesessionname)
+ [错误：未授权执行 sts:AssumeRoleWithSAML（服务：AWSSecurityTokenService；状态代码：403；错误代码：AccessDenied）](#troubleshoot_saml_missing-role)
+ [错误：AuthnResponse 中的 RoleSessionName 必须匹配 [a-zA-Z\$10-9\$1=,.@-]\$12,64\$1（服务：AWSSecurityTokenService；状态代码：400；错误代码：InvalidIdentityToken）](#troubleshoot_saml_invalid-rolesessionname)
+ [错误：源身份必须匹配 [a-zA-Z\$10-9\$1=,.@-]\$12,64\$1 且不能以 `"aws:"` 开始（服务：AWSSecurityTokenService；状态代码：400；错误代码：InvalidIdentityToken）](#troubleshoot_saml_invalid-sourceidentity)
+ [错误：响应签名无效（服务：AWSSecurityTokenService；状态代码：400；错误代码：InvalidIdentityToken）](#troubleshoot_saml_invalid-metadata)
+ [错误：私钥无效。](#troubleshoot_saml_invalid-private-key)
+ [错误：无法删除私有密钥。](#troubleshoot_saml_invalid-remove-key)
+ [错误：无法删除私有密钥，因为密钥 ID 与私有密钥不匹配。](#troubleshoot_saml_invalid-remove-key-mismatch)
+ [错误：无法担任角色：指定提供商中没有发布者（服务：AWSOpenIdDiscoveryService；状态代码：400；错误代码：AuthSamlInvalidSamlResponseException）](#troubleshoot_saml_issuer-mismatch)
+ [错误：无法解析元数据。](#troubleshoot_saml_issuer-metadata)
+ [错误：无法更新身份提供商。没有为元数据或加密断言定义任何更新。](#troubleshoot_saml_unable-to-update)
+ [错误：无法将断言加密模式设置为“必需”，因为未提供私有密钥。](#troubleshoot_saml_issuer-private-key-required)
+ [错误：无法在同一请求中添加和删除私钥。仅为两个参数中的一个参数设置值。](#troubleshoot_saml_add-remove-keys)
+ [错误：指定的提供商不存在。](#troubleshoot_saml_provider-doesnotexist)
+ [错误：请求的 DurationSeconds 超过为该角色设置的 MaxSessionDuration。](#troubleshoot_saml_duration-exceeds)
+ [错误：已达到私有密钥限制 2。](#troubleshoot_saml_private-key-exceeds)
+ [错误：响应不包含所需受众。](#troubleshoot_saml_required-audience)

## 错误：您的请求包含无效的 SAML 响应。要注销，请单击此处。
<a name="troubleshoot_saml_invalid-response"></a>

当来自身份提供商的 SAML 响应没有包含将 `Name` 设置为 `https://aws.amazon.com/SAML/Attributes/Role` 的属性时，会出现此错误。属性必须包含一个或多个 `AttributeValue` 元素，每个元素中包含以逗号分隔的一对字符串：
+ 用户可以映射到的角色的 ARN
+ SAML 提供商的 ARN

当身份提供者发送的 SAML 属性值包含前导或尾随空格，或者 SAML 属性值中包含其他无效字符时，也会发生该错误。有关 SAML 属性的预期值的更多信息，请参阅[为身份验证响应配置 SAML 断言。](id_roles_providers_create_saml_assertions.md)

有关更多信息，请参阅 [为身份验证响应配置 SAML 断言。](id_roles_providers_create_saml_assertions.md)。要在浏览器中查看 SAML 响应，请按照[在您的浏览器中查看 SAML 响应](troubleshoot_saml_view-saml-response.md)中列出的步骤操作。

## 错误：AuthnResponse 中需要 RoleSessionName（服务：AWSSecurityTokenService；状态代码：400；错误代码：InvalidIdentityToken）
<a name="troubleshoot_saml_missing-rolesessionname"></a>

当来自身份提供商的 SAML 响应没有包含将 `Name` 设置为 `https://aws.amazon.com/SAML/Attributes/RoleSessionName` 的属性时，会出现此错误。属性值是用户的标识符，通常是用户 ID 或电子邮件地址。

有关更多信息，请参阅 [为身份验证响应配置 SAML 断言。](id_roles_providers_create_saml_assertions.md)。要在浏览器中查看 SAML 响应，请按照[在您的浏览器中查看 SAML 响应](troubleshoot_saml_view-saml-response.md)中列出的步骤操作。

## 错误：未授权执行 sts:AssumeRoleWithSAML（服务：AWSSecurityTokenService；状态代码：403；错误代码：AccessDenied）
<a name="troubleshoot_saml_missing-role"></a>

当在 SAML 响应中指定的 IAM 角色有拼写错误或者不存在时，会出现此错误。确保使用角色的确切名称，因为角色名称区分大小写。在 SAML 服务提供商配置中更正角色的名称。

只有当角色信任策略包含 `sts:AssumeRoleWithSAML` 操作时，才允许您访问。如果您的 SAML 断言配置为使用 [`PrincipalTag` 属性](id_roles_providers_create_saml_assertions.md#saml_role-session-tags)，则信任策略还必须包含 `sts:TagSession` 操作。有关会话标签的更多信息，请参阅 [在 Amazon STS 中传递会话标签](id_session-tags.md)。

如果角色信任策略中没有 `sts:SetSourceIdentity` 权限，则可能发生此错误。如果您的 SAML 断言配置为使用 [`SourceIdentity`](id_roles_providers_create_saml_assertions.md#saml_sourceidentity) 属性，则信任策略还必须包含 `sts:SetSourceIdentity` 操作。更多有关源身份的信息，请参阅 [监控和控制使用所担任角色执行的操作](id_credentials_temp_control-access_monitor.md)。

如果联合主体没有担任该角色的权限，则会出现此错误。该角色必须具有将 IAM SAML 身份提供商的 ARN 指定为 `Principal` 的信任策略。角色还包含控制哪些用户可以担任该角色的条件。确保您的用户满足条件要求。

如果 SAML 响应中没有包含 `Subject` 的 `NameID`，也会出现此错误。

有关更多信息，请参阅[使 SAML 2.0 联合主体能够访问 Amazon Web Services 管理控制台](id_roles_providers_enable-console-saml.md)和[为身份验证响应配置 SAML 断言。](id_roles_providers_create_saml_assertions.md)。要在浏览器中查看 SAML 响应，请按照[在您的浏览器中查看 SAML 响应](troubleshoot_saml_view-saml-response.md)中列出的步骤操作。

## 错误：AuthnResponse 中的 RoleSessionName 必须匹配 [a-zA-Z\$10-9\$1=,.@-]\$12,64\$1（服务：AWSSecurityTokenService；状态代码：400；错误代码：InvalidIdentityToken）
<a name="troubleshoot_saml_invalid-rolesessionname"></a>

如果 `RoleSessionName` 属性值太长或者包含无效字符，则会出现此错误。最大有效长度为 64 个字符。

有关更多信息，请参阅 [为身份验证响应配置 SAML 断言。](id_roles_providers_create_saml_assertions.md)。要在浏览器中查看 SAML 响应，请按照[在您的浏览器中查看 SAML 响应](troubleshoot_saml_view-saml-response.md)中列出的步骤操作。

## 错误：源身份必须匹配 [a-zA-Z\$10-9\$1=,.@-]\$12,64\$1 且不能以 `"aws:"` 开始（服务：AWSSecurityTokenService；状态代码：400；错误代码：InvalidIdentityToken）
<a name="troubleshoot_saml_invalid-sourceidentity"></a>

如果 `sourceIdentity` 属性值太长或者包含无效字符，则会出现此错误。最大有效长度为 64 个字符。更多有关源身份的信息，请参阅 [监控和控制使用所担任角色执行的操作](id_credentials_temp_control-access_monitor.md)。

有关创建 SAML 断言的更多信息，请参阅 [为身份验证响应配置 SAML 断言。](id_roles_providers_create_saml_assertions.md)。要在浏览器中查看 SAML 响应，请按照[在您的浏览器中查看 SAML 响应](troubleshoot_saml_view-saml-response.md)中列出的步骤操作。

## 错误：响应签名无效（服务：AWSSecurityTokenService；状态代码：400；错误代码：InvalidIdentityToken）
<a name="troubleshoot_saml_invalid-metadata"></a>

在身份提供商的联合身份元数据与 IAM 身份提供商的元数据不匹配时，会出现此错误。例如，身份服务提供商的元数据文件可能已更改，以便更新过期的证书。从身份服务提供商下载更新后的 SAML 元数据文件。然后在 Amazon 身份提供商实体中更新它，该实体在 IAM 中使用 `aws iam update-saml-provider` 跨平台 CLI 命令或 `Update-IAMSAMLProvider` PowerShell cmdlet 定义。

## 错误：私钥无效。
<a name="troubleshoot_saml_invalid-private-key"></a>

如果您的私钥文件格式不正确，可能会发生此错误。此错误可能会提供有关私钥无效原因的其他详细信息：
+ 密钥已加密。
+ 无法识别密钥格式。私钥文件必须是 .pem 文件。

在 Amazon Web Services 管理控制台 中 [在 IAM 中创建 SAML 身份提供者](id_roles_providers_create_saml.md) 时，必须从身份提供商处下载私有密钥以提供给 IAM 来启用加密。私有密钥必须是使用 AES-GCM 或 AES-CBC 加密算法解密 SAML 断言的 .pem 文件。

## 错误：无法删除私有密钥。
<a name="troubleshoot_saml_invalid-remove-key"></a>

当 SAML 加密设置为“必需”时，可能会发生此错误，并且您的请求会删除 IAM SAML 提供商的唯一私有解密密钥。有关轮换私有密钥的更多信息，请参阅 [管理 SAML 加密密钥](id_roles_providers_create_saml.md#id_federation_manage-saml-encryption)。

## 错误：无法删除私有密钥，因为密钥 ID 与私有密钥不匹配。
<a name="troubleshoot_saml_invalid-remove-key-mismatch"></a>

如果私有密钥的 `keyId` 值与身份提供商的私有密钥文件的任一密钥 ID 不匹配，则可能发生此错误。

当您使用 [update-saml-provider](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/update-saml-provider.html) 或 [UpdateSAMLProvider](https://docs.amazonaws.cn/IAM/latest/APIReference/API_UpdateSAMLProvider.html) API 操作删除 SAML 加密私有密钥时，`RemovePrivateKey` 中的值必须是附加到您的身份提供商的私有密钥文件的有效密钥 ID。

## 错误：无法担任角色：指定提供商中没有发布者（服务：AWSOpenIdDiscoveryService；状态代码：400；错误代码：AuthSamlInvalidSamlResponseException）
<a name="troubleshoot_saml_issuer-mismatch"></a>

如果 SAML 响应中的颁发者与联合元数据文件中声明的颁发者不匹配，则可能会出现该错误。在 IAM 中创建身份提供商时，元数据文件将上传到 Amazon 中。

## 错误：无法解析元数据。
<a name="troubleshoot_saml_issuer-metadata"></a>

如果您的元数据文件没有正确格式化，则可能发生此错误。

在 Amazon Web Services 管理控制台 中[创建或管理 SAML 身份提供商](id_roles_providers_create_saml.md#idp-manage-identityprovider-console)时，您必须从您的身份提供商处检索 SAML 元数据文档。

此元数据文件包括颁发者名称、过期信息以及可用来验证从 IdP 处收到的 SAML 身份验证响应 (断言) 的密钥。元数据文件必须采用不含字节顺序标记 (BOM) 的 UTF-8 格式编码。要删除 BOM，您可以使用 Notepad\$1\$1 等文本编辑工具以 UTF-8 格式对文件进行编码。

作为 SAML 元数据文档的一部分，X.509 证书必须使用长度至少为 1024 位的密钥。此外，X.509 证书也不能有任何重复的扩展名。您可以使用扩展程序，但扩展程序只能在证书中显示一次。如果 X.509 证书不符合任一条件，则 IdP 将创建失败，并返回“Unable to parse metadata”这一错误消息。

如 [SAML V2.0 元数据互操作性配置文件 1.0 版](https://docs.oasis-open.org/security/saml/Post2.0/sstc-metadata-iop-os.html)所定义，IAM 既不会评估 SAML 元数据文档的 X.509 证书，也不会在该证书过期时采取任何行动。如果您担心 X.509 证书过期，建议您监控证书到期日期，并根据贵组织的治理和安全策略来轮换证书。

## 错误：无法更新身份提供商。没有为元数据或加密断言定义任何更新。
<a name="troubleshoot_saml_unable-to-update"></a>

如果使用 `update-saml-provider` CLI 或 `UpdateSAMLProvider` API 操作，但未在请求参数中提供更新值，则可能会发生此错误。有关更新 IAM SAML 提供商的更多信息，请参阅 [在 IAM 中创建 SAML 身份提供者](id_roles_providers_create_saml.md)。

## 错误：无法将断言加密模式设置为“必需”，因为未提供私有密钥。
<a name="troubleshoot_saml_issuer-private-key-required"></a>

如果之前未上传私有解密密钥，并且尝试将 SAML 加密设置为“必需”，但请求中未包含私有密钥，则可能会发生此错误。

在使用 `create-saml-provider` CLI、`CreateSAMLProvider` API、`update-saml-provider` CLI 或 `UpdateSAMLProvider` API 操作要求加密的 SAML 断言时，请确保为 IAM SAML 提供商定义了私有密钥。

## 错误：无法在同一请求中添加和删除私钥。仅为两个参数中的一个参数设置值。
<a name="troubleshoot_saml_add-remove-keys"></a>

如果添加和删除私钥值都包含在同一请求中，则可能会发生此错误。

当您使用 [update-saml-provider](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/update-saml-provider.html) 或 [UpdateSAMLProvider](https://docs.amazonaws.cn/IAM/latest/APIReference/API_UpdateSAMLProvider.html) API 操作来轮换 SAML 加密私有密钥文件时，您只能在请求中添加或删除私有密钥。如果在删除私有密钥的同时添加私有密钥，则操作会失败。有关轮换私有密钥的更多信息，请参阅 [管理 SAML 加密密钥](id_roles_providers_create_saml.md#id_federation_manage-saml-encryption)。

## 错误：指定的提供商不存在。
<a name="troubleshoot_saml_provider-doesnotexist"></a>

如果 SAML 断言中的提供商名称与 IAM 中的提供商名称不匹配，则可能会出现该错误。有关查看提供商名称的更多信息，请参阅[在 IAM 中创建 SAML 身份提供者](id_roles_providers_create_saml.md)。

## 错误：请求的 DurationSeconds 超过为该角色设置的 MaxSessionDuration。
<a name="troubleshoot_saml_duration-exceeds"></a>

如果从 Amazon CLI 或 API 中担任角色，则可能会出现该错误。

在使用 [assume-role-with-saml](https://docs.amazonaws.cn/cli/latest/reference/sts/assume-role-with-saml.html) CLI 或 [AssumeRoleWithSAML](https://docs.amazonaws.cn/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API 操作担任角色时，您可以为 `DurationSeconds` 参数指定一个值。您可以指定 900 秒 (15 分钟) 到角色的最大会话持续时间设置之间的值。如果指定的值高于该设置，操作将失败。例如，如果您指定的会话持续时间为 12 小时，但管理员设置的最大会话持续时间为 6 小时，您的操作将失败。要了解如何查看您的角色的最大值，请参阅[更新角色的最长会话持续时间](id_roles_update-role-settings.md#id_roles_update-session-duration)。

## 错误：已达到私有密钥限制 2。
<a name="troubleshoot_saml_private-key-exceeds"></a>

如果您试图将私有密钥添加到身份提供商，则可能会发生此错误。

每个身份提供商最多可以保存两个私有密钥。当您使用 [update-saml-provider](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/update-saml-provider.html) 或 [UpdateSAMLProvider](https://docs.amazonaws.cn/IAM/latest/APIReference/API_UpdateSAMLProvider.html) API 操作来添加第三个私有密钥时，操作会失败。

删除已过期的私有密钥，然后再添加新的私有密钥。有关轮换私有密钥的更多信息，请参阅 [管理 SAML 加密密钥](id_roles_providers_create_saml.md#id_federation_manage-saml-encryption)。

## 错误：响应不包含所需受众。
<a name="troubleshoot_saml_required-audience"></a>

如果受众 URL 与 SAML 配置中的身份提供者不匹配，则可能会出现此错误。确保您的身份提供者（IdP）依赖方标识符与 SAML 配置中提供的受众 URL（实体 ID）完全匹配。