如何在 OpenSearch Service 中配置 SAML 2.0 身份验证并进行故障排除？

解决方法

有关如何为 OpenSearch Dashboard 配置 SAML 2.0 的信息，请参阅 OpenSearch Dashboard 的 SAML 身份验证。

如果您在设置 SAML 2.0 身份验证时遇到问题，请根据您遇到的问题执行以下故障排除操作。

您收到 "Your request: '/some/path' is not allowed" 错误

要对此问题进行故障排除，请确保为 IdP 使用正确的单点登录 URL。

此外，请验证是否使用了适用于身份验证类型的正确 URL：

• 对于服务提供商 (SP) 发起的身份验证，请使用 DashboardsURL/_opendistro/_security/saml/acs。
• 对于 IdP 发起的身份验证，请使用 DashboardsURL/_opendistro/_security/saml/acs/idpinitiated。
  **注意：**请将 DashboardURL 替换为您的域的 OpenSearch Dashboard URL。

您收到 "Please provide valid identity provider metadata document to enable SAML" 错误

要对此问题进行故障排除，请执行以下操作验证来自 IdP 的元数据 XML 文件：

• 使用 XML 验证工具检查元数据 XML 文件中是否存在错误。例如，使用 W3Schools 网站上的 XML 验证器。
• 验证元数据是否符合 SAML 2.0 标准。有关更多信息，请参阅 Oasis 网站上的安全断言标记语言 (SAML) V2.0 技术概述。
• 确认元数据 XML 文件中包含了所有必需的元素。

如果更新了文件，请完成以下步骤以更新 OpenSearch Service SAML 2.0 配置中的元数据：

1. 打开 OpenSearch Service 控制台。
2. 选择 Domains（域）。
3. 选择您的域。
4. 选择 Domain details（域详细信息）。
5. 选择 Edit security configuration（编辑安全配置）。
6. 在 SAML Authentication（SAML 身份验证）下，选择 Edit（编辑）。
7. 上传或输入更新后的元数据。
8. 选择 Save changes（保存更改）。

AWS 管理控制台中未显示 SAML 2.0 配置选项

当您使用已过时的 OpenSearch Service 软件版本时，就会出现此问题。

要检查您的软件版本，请完成以下步骤：

1. 打开 OpenSearch Service 控制台。
2. 选择 Domains（域）。
3. 选择您的域。
4. 查看您的 OpenSearch Service 软件版本。如果您使用的是先前版本，请启动服务软件更新。
5. 刷新浏览器，然后检查 SAML 2.0 配置选项。

如果您仍然遇到问题，请提交 AWS Support 案例。

您收到 "SAML configuration error: Something went wrong while retrieving the SAML configuration, please check your settings" 错误

要对 "SAML configuration error" 错误进行故障排除，请检查配置问题。

检查您的 SP 实体 ID 和单点登录 URL

检查 IdP 配置中的 SP 实体 ID 和单点登录 URL。

然后，完成以下步骤以检查您的 OpenSearch Service 域配置：

1. 打开 OpenSearch Service 控制台。
2. 选择 Domains（域）。
3. 选择您的域。
4. 选择 Domain details（域详细信息）。
5. 选择 Edit security configuration（编辑安全配置）。
6. 检查 SP 实体 ID 和单点登录 URL 的值。IdP 配置必须使用 OpenSearch Service 域中的值。如有需要，请更新您的 IdP 配置。

检查您的 IdP 元数据文件

完成以下步骤：

1. 从您的 IdP 生成元数据文件。
2. 打开 OpenSearch Service 控制台。
3. 选择 Domains（域）。
4. 选择您的域。
5. 选择 Domain details（域详细信息）。
6. 选择 Edit security configuration（编辑安全配置）。
7. 在 SAML authentication（SAML 身份验证）下，确保安全配置中的值与元数据文件中的 IdP 实体 ID 相匹配。如果二者不匹配，请选择 Edit（编辑），然后上传或更新元数据。
8. 选择 Save changes（保存更改）。

查看您的域访问策略

确保您的域访问策略允许访问 OpenSearch Dashboard 和 _plugins/_security/* 端点。

策略示例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "es:ESHttp*",
      "Resource": [
        "arn:aws:es:region:account-id:domain/domain-name/_dashboards*",
        "arn:aws:es:region:account-id:domain/domain-name/_plugins/_security/*",
        ...
      ]
    }
  ]
}

**注意：**请将 region 替换为您的 AWS 区域，将 account-id 替换为您的 AWS 账户 ID，并将 domain-name 替换为您的域名。对于已启用精细访问控制的域，最佳做法是使用开放访问策略。

查看您的 IdP 文档

查看您的 IdP 文档，了解其他所需的 SAML 2.0 配置步骤。

您收到 "Missing role: No roles available for this user, please contact your system administrator" 错误

此错误通常在您成功进行身份验证，但未将 SAML 2.0 断言中的用户名或后端角色映射到任何角色时出现。

要对此问题进行故障排除，请完成以下步骤。

1. 要查看您的 SAML 2.0 断言，请在 Firefox 网站上安装 SAML-tracer 等浏览器扩展程序，或在 Chrome 应用商店网站上安装 SAML-tracer。
2. 在 SAML 2.0 断言中，检查以下设置：
   验证 IdP 中的用户名是否与 SAML 2.0 断言中主题键元素的值相匹配。例如，如果主题键为电子邮件，请检查 SAML 2.0 断言中电子邮件元素的值。如果没有主题键元素，则用户名为 NameID 的值。
   验证 IdP 中的后端角色是否与 SAML 2.0 断言中角色键元素的值相匹配。例如，如果角色键为组，则检查 SAML 2.0 断言中组元素的值。通常后端角色为组或用户。
3. 以管理员用户身份登录 OpenSearch Dashboard，然后运行以下命令来检查现有角色映射：

   GET _plugins/_security/api/rolesmapping

   在输出中，检查角色映射是否与 SAML 断言中的用户名和后端角色相匹配。如果映射不匹配，请继续下一步。
4. 使用 SAML 2.0 中的用户名或后端角色创建新的角色映射。要将用户或后端角色映射到 OpenSearch 中的内部角色，请参阅 OpenSearch 网站上的](https://docs.opensearch.org/1.0/security-plugin/access-control/users-roles/#map-users-to-roles)将用户映射到角色[。
   **重要事项：**角色映射区分大小写。确保与 SAML 2.0 断言中的值完全一致。

当您尝试访问 OpenSearch Dashboard 时，浏览器会重定向或收到 HTTP 500 错误

此问题通常在您遇到角色配置问题时出现。

要对此问题进行故障排除，请执行以下操作：

• 检查 SAML 2.0 断言中的角色是否使用过多字符。
  **注意：**OpenSearch 版本 2.5 及更早版本的字符配额上限为 1,500 个字符。
• 减少在 IdP 配置中分配给用户的角色数量。
• 如果可能，请升级到 OpenSearch 版本 2.7 或更高版本。
  **注意：**OpenSearch 的较新版本将 SAML 2.0 断言的字符配额上限增加到了 5,000 个字符。
• 基于组而非单个角色来分配角色。
• 检查浏览器的 Cookie 存储配额，然后根据需要清除 Cookie。

无法注销 ADFS

如果您的元数据文件包含**<SingleLogoutService/>**元素，则无法注销 Microsoft Active Directory 联合身份验证服务 (ADFS)。

要对此问题进行故障排除，请完成以下步骤：

1. 从 ADFS 服务器下载 IdP 元数据 XML 文件。
2. 在文本编辑器中打开该 XML 文件。
3. 移除整个**<SingleLogoutService />**元素。
4. 保存文件。
5. 打开 OpenSearch Service 控制台。
6. 选择 Domains（域）。
7. 选择您的域。
8. 选择 Domain details（域详细信息）。
9. 选择 Edit security configuration（编辑安全配置）。
10. 在 SAML Authentication（SAML 身份验证）下，选择 Edit（编辑）。
11. 上传或输入更新后的元数据。
12. 选择 Save changes（保存更改）。

您收到 "Could not find entity descriptor for __PATH__" 错误

SAML 2.0 响应中的实体 ID 必须与 OpenSearch Service 中 SAML 2.0 元数据中的实体 ID 一致。如果不一致，您会收到 "Could not find entity descriptor" 错误消息。

要对此问题进行故障排除，请完成以下步骤：

1. 为您的 OpenSearch Service 域激活 Amazon CloudWatch 错误日志。
2. 在身份验证尝试失败后立即检查日志，以查找不匹配的值。例如，在 Could not find entity descriptor for _PATH_ 中，不匹配的值为 _PATH_。
3. 打开您的 IdP 配置以了解不匹配的原因。检查错误消息中提及的实体 ID。
4. 更新 SAML 2.0 元数据文件中的 IdP 实体 ID 字段，使其与 IdP 中的值完全一致。
   -or-
   更新您的 IdP 配置，使其与您在 OpenSearch Service 中配置 SAML 2.0 时所使用的 SAML 2.0 元数据中的值相匹配。

您收到 "Signature validation failed.SAML response rejected" 错误

此错误通常在您的 IdP 元数据中的签名证书已过期或已轮换时出现。

要对此问题进行故障排除，请完成以下步骤：

1. 请联系您的 IdP 管理员获取当前签名证书。
2. 下载签名证书元数据 XML 文件。
3. 打开 OpenSearch Service 控制台。
4. 选择您的域。
5. 选择 Domain details（域详细信息）。
6. 选择 Edit security configuration（编辑安全配置）。
7. 在 SAML Authentication（SAML 身份验证）下，选择 Edit（编辑）。
8. 上传或输入更新后的元数据。
9. 选择 Save changes（保存更改），然后等待域状态从 PROCESSING（处理中）更改为 ACTIVE（活动）。

您收到 "__PATH__ is not a valid audience for this response" 错误

当 IdP 的 SAML 2.0 响应中的受众与 OpenSearch Service 所期望的受众不匹配时，就会出现此错误。

要对此问题进行故障排除，请完成以下步骤：

1. 检查 OpenSearch Service 域的 Amazon CloudWatch Logs 中的错误日志，以查看有关不匹配值的信息。例如，在 _PATH_ is not a valid audience 中，不匹配的值为 _PATH_。
2. 打开 OpenSearch Service 控制台。
3. 选择您的域。
4. 选择 Domain details（域详细信息）。
5. 选择 Edit security configuration（编辑安全配置）。
6. 在 SAML authentication（SAML 身份验证）下，记下 Service provider entity ID（服务提供商实体 ID）的值。在您的 IdP 配置中，检查 Audience（受众）或 SP entity ID（SP 实体 ID）设置，确保其与 Service provider entity ID（服务提供商实体 ID）的值完全一致。
7. 如果您使用自定义端点，请确保受众与您的自定义端点 URL 相匹配。
8. 保存您的 IdP 配置中的更改。

您的浏览器收到 HTTP 400 错误，响应中显示 "Invalid Request Id"

当您使用 IdP 发起的单点登录，但使用 SAML 2.0 和 SP 发起的单点 URL 配置了该域时，通常会出现此问题。

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

1. 打开您的 IdP 配置设置。
2. 对于 SSO URL 或 ACS URL，请将 URL 格式从 DashboardsURL/_opendistro/_security/saml/acs 更改为 DashboardsURL/_opendistro/_security/saml/acs/idpinitiated。
   **注意：**请将 DashboardURL 替换为您的域的 OpenSearch Dashboard URL。
3. 保存配置更改，然后测试 IdP 发起的单点登录。

您收到 "The response was received at __PATH__ instead of __PATH__" or "The response has an InResponseTo attribute, while no InResponseTo was expected" 错误消息

当 IdP 中的目标配置不正确时，就会出现这些错误。

要对此问题进行故障排除，请完成以下步骤：

1. 在您的 IdP 配置中，检查 SSO URL 或 ACS URL 设置。
2. 根据您配置单点登录的方式更新 Destination（目标）字段：
   对于 SP 发起的单点登录，请将目标设置为 DashboardsURL/_opendistro/_security/saml/acs
   对于 IdP 发起的流程，请将目标设置为 DashboardsURL/_opendistro/_security/saml/acs/idpinitiated
   **注意：**请将 DashboardURL 替换为您的域的 OpenSearch Dashboard URL。
3. 保存您的 IdP 配置。
4. 测试您的单点登录身份验证方法。

相关信息

使用 Okta 为 OpenSearch Service 构建 SAML 联合身份验证