对接 Keycloak (SAML)

v2.1.0 版本可用

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

先决条件

  • 您必须有一个Keycloak IdP 服务器

  • 在 Keycloak 中,创建一个新的 SAML 客户端,设置如下。参见Keycloak 文档获得帮助。

    设置
    Sign DocumentsON 1
    Sign AssertionsON 1
    所有其它ON/OFF设置OFF
    Client IDhttps://yourRancherHostURL/v1-saml/keycloak/saml/metadata2
    Client Name<CLIENT_NAME> (e.g. rancher)
    Client ProtocolSAML
    Valid Redirect URIhttps://yourRancherHostURL/v1-saml/keycloak/saml/acs
    • 1:您可以选择启用这些设置中的一个或两个。
    • 2:在配置和保存 SAML 提供者之前,不会生成 Rancher SAML 元数据。 keycloak-saml-client-configuration

    在新的 SAML 客户端中,创建 Mappers 来暴露用户字段。

    • 添加所有 “内置协议映射器” keycloak-saml-client-builtin-mappers
    • 创建一个新的 “组列表 “映射器,将成员属性映射到用户的组。 keycloak-saml-client-group-mapper
  • 从 Keycloak 客户端导出metadata.xml文件: 在安装选项卡中,选择SAML Metadata IDPSSODescriptor格式选项并下载文件。

说明: Keycloak 6.0.0 及以上版本不再在 “安装 “标签下提供 IDP 元数据。 你仍然可以从以下网址获取 XML:

https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}/protocol/saml/descriptor

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

  • EntitiesDescriptor中所有不存在的属性复制到 EntityDescriptor中。
  • 删除开头的<EntitiesDescriptor>标签。
  • 删除结尾的的</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>

Copy

在 Rancher 中配置 Keycloak

  1. 全局视图中,从主菜单中选择安全 > 认证

  2. 选择Keycloak

  3. 完成配置 Keycloak 账户表单。有关填写表格的帮助,请参阅配置参考

  4. 完成配置 Keycloak 帐户表单后,单击页面底部的启用 Keycloak 认证进行身份验证。

    Rancher 将重定向到 IdP 登录页面。输入 Keycloak IdP 系统的身份验证凭据,以验证您的 Rancher Keycloak 配置。

    注: 您可能需要禁用弹出窗口拦截器以访问 IdP 登录页面。

结果: Rancher 被配置为使用 Keycloak 认证。您的用户现在可以使用 Keycloak 账号登录 Rancher。

SAML 身份验证提供者警告:

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

配置参考

Field描述
Display Name Field包含用户的显示名称的属性。例如: givenName
User Name Field包含用户名/姓名的属性。 例如: email
UID Field一个对每个用户来说都是独一无二的属性。 例如: email
Groups Field为管理组成员资格创建条目。 例如: member
Entity ID FieldKeycloak 客户端需要配置为客户端 ID 的 ID。 默认: https://yourRancherHostURL/v1-saml/keycloak/saml/metadata
Rancher API HostRancher Server 的 URL。
Private Key / Certificate一个密钥/证书对,在 Rancher 和你的 IdP 之间创建一个安全的外壳。
IDP-metadata从 IdP 服务器导出的 metadata.xml 文件。

提示:你可以使用 openssl 命令生成一个密钥/证书对。比如说:

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

Copy

附录: 故障诊断

如果在测试到 Keycloak 服务器的连接时遇到了问题,首先需要再次检查 SAML 客户机的配置选项。您还可以检查 Rancher 日志,以帮助确定问题的原因。调试日志可能包含关于错误的更详细的信息。请参考本文档中的如何启用调试日志

没有被重定向到 Keycloak

当您单击启用 Keycloak 认证时,没有被重定向到 Keycloak IdP。

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

IdP 登录后显示禁止消息

您被正确地重定向到 Keycloak IdP 登录页面,可以输入凭据,但得到一个禁止的消息。

  • 检查 Rancher 调试日志。
  • 如果日志显示ERROR: either the Response or Assertion must be signed,确保Sign DocumentsSign 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