本文档采用自动化机器翻译技术翻译。 尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。 若出现任何内容不一致情况，请以原始 英文 版本为准，且原始英文版本为权威文本。

配置 Keycloak (OIDC)

如果您的组织使用 Keycloak 身份提供者 (IdP) 进行用户身份验证，您可以配置 Rancher 以允许用户使用其 IdP 凭据登录。Rancher 支持使用 OpenID Connect (OIDC) 协议和 SAML 协议与 Keycloak 集成。在与 Rancher 一起使用时，这两种实现功能上是等效的。本页面描述了配置 Rancher 以使用 OIDC 协议与 Keycloak 一起工作的过程。

如果您更喜欢使用 SAML 协议与 Keycloak 一起使用，请参考 此页面。

如果您有一个使用 SAML 协议的现有配置并想切换到 OIDC 协议，请参考 本节。

先决条件

  • 在 Rancher 上，Keycloak (SAML) 已禁用。

  • 您必须配置一个 Keycloak IdP 服务器。

  • 请遵循 Keycloak 文档 创建一个具有以下设置的新 OIDC 客户端。

    设置 值

    Client ID

    <client-id> (例如 rancher)

    Name

    <client-name> (例如 rancher)

    Client type

    OpenID Connect

    Client authentication

    ON

    Valid Redirect URI

    https://yourRancherHostURL/verify-auth

  • 在新的 OIDC 客户端中，创建 映射器 以暴露用户字段。

    1. 在导航菜单中，单击 客户端。

    2. 单击 客户端列表 选项卡。

    3. 找到并单击您创建的客户端。

    4. 单击 客户端范围 选项卡。

    5. 找到并单击标记为 <client-name>-dedicated 的链接。例如，如果您将客户端命名为 rancher，请查找名为 rancher-dedicated 的链接。

    6. 单击 映射器 选项卡。

    7. 单击 配置新映射器。如果您已经配置了现有的映射器，请单击 添加映射器 旁边的箭头，然后选择 按配置。重复此过程并创建以下映射器：

      • 从映射表中选择组成员资格，并使用以下设置配置一个新的“组映射器”。对于未提及的设置，请使用默认值。

        设置 值

        Name

        Groups Mapper

        Mapper Type

        Group Membership

        Token Claim Name

        groups

        Full group path

        OFF

        Add to ID token

        OFF

        Add to access token

        OFF

        Add to user info

        ON

      • 从映射表中选择受众，并使用以下设置配置一个新的“客户端受众”。对于未提及的设置，请使用默认值。

        设置 值

        Name

        Client Audience

        Mapper Type

        Audience

        Included Client Audience

        <client-name>

        Add to ID token

        OFF

        Add to access token

        ON

      • 从映射表中选择组成员资格，并使用以下设置配置一个新的“组路径”。对于未提及的设置，请使用默认值。

        设置 值

        Name

        Group Path

        Mapper Type

        Group Membership

        Token Claim Name

        full_group_path

        Full group path

        ON

        Add to ID token

        ON

        Add to access token

        ON

        Add to user info

        ON

  • 将以下角色映射添加到所有需要查询Keycloak用户的用户或组。

    • 用户

    • 组

    1. 在导航菜单中，单击用户。

    2. 单击您要添加角色映射的用户。

    3. 单击 角色映射 选项卡。

    4. 单击 指派角色。

    5. 选择以下角色：

      • query-users

      • query-groups

      • view-users

    6. 单击 指派。

    1. 在导航菜单中，单击组。

    2. 单击您要添加角色映射的组。

    3. 单击 角色映射 选项卡。

    4. 单击 指派角色。

    5. 选择以下角色：

      • query-users

      • query-groups

      • view-users

    6. 单击指派。

在 Rancher 中配置 Keycloak

  1. 在 Rancher UI 中，单击 ☰ > 用户与身份验证。

  2. 在左侧导航栏中，点击 身份验证提供者。

  3. 选择 Keycloak (OIDC)。

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

    使用 生成 选项配置 端点 部分时，Rancher将 /auth 作为 发行者 和 身份验证端点 字段中的上下文路径的一部分，这仅适用于Keycloak 16或更早版本。您必须使用 指定 选项配置 Keycloak 17 及更新版本的端点，这些版本已 迁移到Quarkus。

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

    Rancher 会将您重定向到 IdP 登录页面。输入与Keycloak IdP进行身份验证的凭据，以验证您的Rancher Keycloak配置。

    您可能需要禁用弹出窗口拦截器才能查看 IdP 登录页面。

*结果：*Rancher 已配置为使用 OIDC 协议与 Keycloak 配合工作。您的用户现在可以使用他们的Keycloak登录信息登录Rancher。

配置参考

字段 说明

客户机 ID

您的 Keycloak 客户端的 Client ID。

客户端密钥

您的 Keycloak 客户端生成的 Secret。在 Keycloak 控制台中，选择 客户端，选择您创建的客户端，选择 凭据 选项卡，并复制 Secret 字段的值。

私钥/证书

用于在Rancher和您的IdP之间创建安全外壳的密钥/证书对。如果在您的Keycloak服务器上启用了HTTPS/SSL，则需要此项。

端点

选择是否使用生成的值填充 Rancher URL、Issue 和 Auth Endpoint 字段，或在不正确时提供手动覆盖。

Keycloak URL

您的Keycloak服务器的URL。

Keycloak领域

创建 Keycloak 客户端的领域名称。

Rancher URL

您的 Rancher 服务器的 URL。

颁发者

您的 IdP 的 URL。

身份验证端点

用户被重定向到进行身份验证的 URL。

从SAML迁移到OIDC

本节描述了从使用 Rancher 和 Keycloak (SAML) 过渡到 Keycloak (OIDC) 的过程。

  1. 重新配置 Keycloak。

    1. 根据 前提条件 配置一个新的 OpenID Connect 客户端。确保设置相同的 Valid Redirect URIs。

    2. 根据 前提条件 为新客户端配置映射器。

  2. 在配置 Rancher 使用 Keycloak (OIDC) 之前，必须先禁用 Keycloak (SAML)。

    1. 在 Rancher UI 中，单击 ☰ > 用户与身份验证。

    2. 在左侧导航栏中，点击 身份验证提供者。

    3. 选择 Keycloak (SAML)。

    4. 单击 禁用。

  3. 按照 在 Rancher 中配置 Keycloak 中的步骤进行操作。

    配置完成后，需要重新应用 Rancher 用户权限，因为它们不会自动迁移。

对PKCE扩展的OIDC支持

Rancher supports the Proof Key for Code Exchange (PKCE) extension (RFC 7636) for OIDC authentication providers. SHA-256 (S256) is the only supported PKCE verification method. To enable this feature, your authentication provider must use PKCE with S256 for authorization requests.

You can enable this feature by selecting Enable PKCE (S256) in your authentication provider configuration in Rancher. Enabling S256 PKCE token verification allows you to mitigate authorization code interception attacks during OIDC authentication flows.

附录：查错

如果您在测试与 Keycloak 服务器的连接时遇到问题，请首先仔细检查您的 OIDC 客户端的配置选项。您还可以检查 Rancher 日志以帮助确定问题的原因。调试日志可能包含有关错误的更详细信息。请参阅如何启用调试日志中的文档。

所有与 Keycloak 相关的日志条目都以 [generic oidc] 或 [keycloak oidc] 开头。

您没有被重定向到 Keycloak。

当您填写 配置 Keycloak OIDC 账户 表单并单击 启用 时，您没有被重定向到您的 IdP。

验证您的 Keycloak 客户端配置。

生成的 Issuer 和 Auth Endpoint 不正确

在 配置 Keycloak OIDC 账户 表单上，将 端点 更改为 Specify (advanced)，并覆盖 Issuer 和 Auth Endpoint 的值。要查找这些值，请转到 Keycloak 控制台，选择 领域设置，选择 常规 选项卡，然后单击 OpenID 端点配置。JSON 输出显示 issuer 和 authorization_endpoint 的值。

Keycloak 错误："无效的 grant_type"

在某些情况下，此错误消息可能会误导，并且是由于错误设置 Valid Redirect URI 导致的。

分配全局角色时无法查看组

如果您在初始设置中使用的用户不属于任何组，则在尝试分配全局角色时无法搜索组。为了解决此问题，您可以：

  1. 手动编辑 authconfig/keycloakoidc 对象以启用组搜索。

    1. 在 Rancher 服务器上：

        kubectl edit authconfigs.management.cattle.io keycloakoidc

    2. 设置 groupSearchEnabled: true。

    3. 保存所做的更改。

  2. 使用分配给 Keycloak 中至少一个组的用户重新配置您的 Keycloak OIDC 设置。

配置OIDC单点注销（SLO）

Rancher supports the ability to configure OIDC Single Logout (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.

Prerequisites

Before configuring OIDC SLO, ensure the following is set up on your IdP:

  • SLO Support: The Log Out behavior configuration section only appears if your OIDC IdP allows for OIDC SLO.

  • Post-Logout Redirect URI: Your Rancher Server URL must be configured as an authorized post-logout redirect URI in your IdP’s OIDC client settings. This URL is used by the IdP to redirect a user back to Rancher after a successful external logout.

OIDC SLO Configuration

Configure the SLO settings when setting up or editing your OIDC authentication provider.

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

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

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

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

    Setting Description

    Log out of Rancher and not authentication provider

    Choosing 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 step

    Choosing this option presents users with a choice of logout method as described above.

  5. If you choose to log out of your IdP, provide an End Session Endpoint. Rancher uses this URL to initiate the external logout.

How to get the End Session Endpoint

The end_session_endpoint is one of the specific URLs published within a standardized JSON object containing the IdP’s metadata and is retrieved from the OIDC Discovery URL. To get the end_session_endpoint from the OIDC Discovery URL, follow these steps:

  1. Obtain the Discovery URL by appending the IdP Issuer URL with the well-known path (.well-known/openid-configuration).

  2. Send an HTTP GET request to the Discovery URL.

  3. In the JSON object, look for the key named end_session_endpoint and retrieve the URL.

    You can also use a curl command to retrieve end_session_endpoint:

    curl -s <ISSUER_URL>/.well-known/openid-configuration | jq '.end_session_endpoint'