配置 Keycloak (SAML)

如果你的组织使用 Keycloak Identity Provider (IdP) 进行用户身份验证，你可以通过配置 Rancher 来允许用户使用 IdP 凭证登录。

先决条件

  • 你必须配置了 Keycloak IdP 服务器。

  • 在 Keycloak 中，使用以下设置创建一个新的 SAML 客户端。如需获取帮助，请参见 Keycloak 文档。

    设置值
    Sign DocumentsON 1
    Sign AssertionsON 1
    所有其他 ON/OFF 设置OFF
    Client ID输入 https://yourRancherHostURL/v1-saml/keycloak/saml/metadata，或在 Rancher Keycloak 配置2 中 Entry ID 字段的值。
    Client Name<CLIENT_NAME> (例如 rancher)
    Client ProtocolSAML
    Valid Redirect URIhttps://yourRancherHostURL/v1-saml/keycloak/saml/acs

    1：可以选择启用这些设置中的一个或两个。2：在配置和保存 SAML 身份提供商之前，不会生成 Rancher SAML 元数据。

    配置 Keycloak (SAML) - 图1

  • 在新的 SAML 客户端中，创建 Mappers 来公开用户字段。

    • 添加所有 “Builtin Protocol Mappers” 配置 Keycloak (SAML) - 图2
    • 创建一个 “Group list” mapper，来将成员属性映射到用户的组： 配置 Keycloak (SAML) - 图3

获取 IDP 元数据

  • Keycloak 5 和更早的版本
  • Keycloak 6-13
  • Keycloak 14+

要获取 IDP 元数据，请从 Keycloak 客户端导出 metadata.xml 文件。 在安装选项卡中，选择SAML 元数据 IDPSSODescriptor 格式选项并下载你的文件。

  1. 在配置中，单击 Realm 设置选项卡。
  2. 点击通用选项卡。
  3. 在端点字段中，单击 SAML 2.0 身份提供者元数据。

验证 IDP 元数据是否包含以下属性：

  1. xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  2. xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  3. xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

某些浏览器（例如 Firefox）可能会渲染/处理文档，使得内容看起来已被修改，并且某些属性看起来可能有缺失。在这种情况下，请使用通过浏览器找到的原始响应数据。

以下是 Firefox 的示例流程，其他浏览器可能会略有不同：

  1. 按下 F12 访问开发者控制台。
  2. 点击 Network 选项卡。
  3. 从表中，单击包含 descriptor 的行。
  4. 在 details 窗格中，单击 Response 选项卡。
  5. 复制原始响应数据。

获得的 XML 以 EntitiesDescriptor 作为根元素。然而，Rancher 希望根元素是 EntityDescriptor 而不是 EntitiesDescriptor。因此，在将这个 XML 传递给 Rancher 之前，请按照以下步骤调整：

  1. 将所有不存在的属性从 EntitiesDescriptor 复制到 EntityDescriptor。
  2. 删除开头的 <EntitiesDescriptor> 标签。
  3. 删除 xml 末尾的 </EntitiesDescriptor>。

最后的代码会是如下：

  1. <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}">
  2. ....
  3. </EntityDescriptor>
  1. 在配置中，单击 Realm 设置选项卡。
  2. 点击通用选项卡。
  3. 在端点字段中，单击 SAML 2.0 身份提供者元数据。

验证 IDP 元数据是否包含以下属性：

  1. xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  2. xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  3. xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

某些浏览器（例如 Firefox）可能会渲染/处理文档，使得内容看起来已被修改，并且某些属性看起来可能有缺失。在这种情况下，请使用通过浏览器找到的原始响应数据。

以下是 Firefox 的示例流程，其他浏览器可能会略有不同：

  1. 按下 F12 访问开发者控制台。
  2. 点击 Network 选项卡。
  3. 从表中，单击包含 descriptor 的行。
  4. 在 details 窗格中，单击 Response 选项卡。
  5. 复制原始响应数据。

在 Rancher 中配置 Keycloak

  1. 在左上角，单击 ☰ > 用户 & 认证。

  2. 在左侧导航栏，单击认证。

  3. 单击 Keycloak SAML。

  4. 填写配置 Keycloak 账号表单。有关填写表单的帮助，请参见配置参考。

  5. 完成配置 Keycloak 账号表单后，单击启用。

    Rancher 会将你重定向到 IdP 登录页面。输入使用 Keycloak IdP 进行身份验证的凭证，来验证你的 Rancher Keycloak 配置。

    配置 Keycloak (SAML) - 图4备注

    你可能需要禁用弹出窗口阻止程序才能看到 IdP 登录页面。

结果：已将 Rancher 配置为使用 Keycloak。你的用户现在可以使用 Keycloak 登录名登录 Rancher。

配置 Keycloak (SAML) - 图5SAML 身份提供商注意事项

  • SAML 协议不支持搜索或查找用户或组。因此，将用户或组添加到 Rancher 时不会对其进行验证。
  • 添加用户时，必须正确输入确切的用户 ID（即 UID 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。
  • 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。
  • 用户组下拉列表仅显示你所属的用户组。如果你不是某个组的成员，你将无法添加该组。

配置参考

字段描述
显示名称字段包含用户显示名称的属性。

示例：givenName
用户名字段包含用户名/给定名称的属性。

示例：email
UID 字段每个用户独有的属性。

示例：email
用户组字段创建用于管理组成员关系的条目。

示例：member
Entity ID 字段Keycloak 客户端中需要配置为客户端的 ID。

默认值：https://yourRancherHostURL/v1-saml/keycloak/saml/metadata
Rancher API 主机Rancher Server 的 URL。
私钥/证书在 Rancher 和你的 IdP 之间创建安全外壳（SSH）的密钥/证书对。
IDP 元数据从 IdP 服务器导出的 metadata.xml 文件。

配置 Keycloak (SAML) - 图6提示

你可以使用 openssl 命令生成一个密钥/证书对。例如：

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

附录：故障排除

如果你在测试与 Keycloak 服务器的连接时遇到问题，请先检查 SAML 客户端的配置选项。你还可以检查 Rancher 日志来查明问题的原因。调试日志可能包含有关错误的更详细信息。详情请参见如何启用调试日志。

不能重定向到 Keycloak

点击使用 Keycloak 认证时，没有重定向到你的 IdP。

  • 验证你的 Keycloak 客户端配置。
  • 确保 Force Post Binding 设为 OFF。

IdP 登录后显示禁止消息

你已正确重定向到你的 IdP 登录页面，并且可以输入凭证，但是之后收到 Forbidden 消息。

  • 检查 Rancher 调试日志。
  • 如果日志显示 ERROR: either the Response or Assertion must be signed，确保 Sign Documents 或 Sign assertions 在 Keycloak 客户端中设置为 ON。

访问 /v1-saml/keycloak/saml/metadata 时返回 HTTP 502

常见原因：配置 SAML 提供商之前未创建元数据。 尝试配置 Keycloak，并将它保存为你的 SAML 提供商，然后访问元数据。

Keycloak 错误：”We’re sorry, failed to process response”

  • 检查你的 Keycloak 日志。
  • 如果日志显示 failed: org.keycloak.common.VerificationException: Client does not have a public key，请在 Keycloak 客户端中将 Encrypt Assertions 设为 OFF。

Keycloak 错误：”We’re sorry, invalid requester”

  • 检查你的 Keycloak 日志。
  • 如果日志显示 request validation failed: org.keycloak.common.VerificationException: SigAlg was null，请在 Keycloak 客户端中将 Client Signature Required 设为 OFF。

Configuring SAML Single Logout (SLO)

Rancher supports the ability to configure SAML SLO. Options include logging out of the Rancher application only, logging out of Rancher and registered applications tied to the external authentication provider, or a prompt asking the user to choose between the previous options. The steps below outline configuration from the application GUI:

配置 Keycloak (SAML) - 图7备注

The Log Out behavior configuration section only appears if the SAML authentication provider allows for SAML SLO.

  1. Sign in to Rancher using a standard user or an administrator role to configure SAML SLO.

  2. In the top left corner, click ☰ > Users & Authentication.

  3. In the left navigation menu, click Auth Provider.

  4. Under the section Log Out behavior, choose the appropriate SLO setting as described below:

    SettingDescription
    Log out of Rancher and not authentication providerChoosing this option will only logout the Rancher application and not external authentication providers.
    Log out of Rancher and authentication provider (includes all other applications registered with authentication provider)Choosing this option will logout Rancher and all external authentication providers along with any registered applications linked to the provider.
    Allow the user to choose one of the above in an additional log out stepChoosing this option presents users with a choice of logout method as described above.