配置 Keycloak (OIDC)

如果你的组织使用 Keycloak Identity Provider (IdP) 进行用户身份验证，你可以通过配置 Rancher 来允许用户使用 IdP 凭证登录。Rancher 支持使用 OpenID Connect (OIDC) 协议和 SAML 协议来集成 Keycloak。与 Rancher 一起使用时，这两种实现在功能上是等效的。本文描述了配置 Rancher 以通过 OIDC 协议与 Keycloak 一起使用的流程。

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

如果你有使用 SAML 协议的现有配置并希望切换到 OIDC 协议，请参见本节。

先决条件

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

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

  • Follow the Keycloak documentation to create a new OIDC client with the settings below.。

    设置 值

    Client ID

    <client-id> (例如 rancher)

    Name

    <client-name> (例如 rancher)

    Client type

    OpenID Connect

    Client authentication

    ON

    Valid Redirect URI

    https://yourRancherHostURL/verify-auth

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

    1. In the navigation menu, click Clients.

    2. Click the Clients list tab.

    3. Find and click the client you created.

    4. Click the Client scopes tab.

    5. Find and click the link labeled <client-name>-dedicated. For example, if you named your client rancher, look for the link named rancher-dedicated.

    6. Click the Mappers tab.

    7. Click Configure a new mapper. If you already have existing mappers configured, click the arrow next to Add mapper and select By configuration. Repeat this process and create these mappers:

      • From the mappings table, select Group Membership and configure a new "Groups Mapper" with the settings below. For settings that are not mentioned, use the default value.

        Setting Value

        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

      • From the mappings table, select Audience and configure a new "Client Audience" with the settings below. For settings that are not mentioned, use the default value.

        Setting Value

        Name

        Client Audience

        Mapper Type

        Audience

        Included Client Audience

        <client-name>

        Add to ID token

        OFF

        Add to access token

        ON

      • From the mappings table, select Group Membership and configure a new "Groups Path" with the settings below. For settings that are not mentioned, use the default value.

        Setting Value

        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

  • Add the following role mappings to all users or groups that need to query the Keycloak users.

    • Users

    • Groups

    1. In the navigation menu, click Users.

    2. Click the user you want to add role mappings to.

    3. Click the Role mapping tab.

    4. Click Assign role.

    5. Select the following roles:

      • query-users

      • query-groups

      • view-users

    6. Click Assign.

    1. In the navigation menu, click Groups.

    2. Click the group you want to add role mappings to.

    3. Click the Role mapping tab.

    4. Click Assign role.

    5. Select the following roles:

      • query-users

      • query-groups

      • view-users

    6. Click Assign.

在 Rancher 中配置 Keycloak

  1. 在 Rancher UI 中，单击 ☰ > 用户 & 认证。

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

  3. 选择 Keycloak (OIDC)

  4. Select Keycloak (OIDC).。

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

    When configuring the Endpoints section using the Generate option, Rancher includes /auth as part of the context path in the Issuer and Auth Endpoint fields, which is only valid for Keycloak 16 or older. You must configure endpoints using the Specify option for Keycloak 17 and newer, which have migrated to Quarkus.

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

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

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

结果：已将 Rancher 配置为使用 OIDC 协议与 Keycloak 一起工作。你的用户现在可以使用 Keycloak 登录名登录 Rancher。

配置参考

字段 描述

客户端 ID

你的 Keycloak 客户端的 Client ID。

客户端密码

你的 Keycloak 客户端生成的 Secret。在 Keycloak 控制台中，单击 Clients，选择你创建的客户端，选择 Credentials 选项卡，然后复制 Secret 字段的值。

私钥/证书

在 Rancher 和你的 IdP 之间创建安全外壳（SSH）的密钥/证书对。如果你的 Keycloak 服务器上启用了 HTTPS/SSL，则为必填。

端点

选择为 Rancher URL、发行者和 Auth 端点字段使用生成的值，还是在不正确时进行手动覆盖。

Keycloak URL

你的 Keycloak 服务器的 URL。

Keycloak Realm

创建 Keycloak 客户端的 Realm 的名称。

Rancher URL

Rancher Server 的 URL。

Issuer

你的 IdP 的 URL。

Auth 端点

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

从 SAML 迁移到 OIDC

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

  1. Reconfigure Keycloak.

    1. Configure a new OpenID Connect client according to the 先决条件. Ensure the same Valid Redirect URIs are set.

    2. Configure mappers for the new client according to the 先决条件.

  2. Before configuring Rancher to use Keycloak (OIDC), Keycloak (SAML) must be first disabled.

    1. In the Rancher UI, click ☰ > Users & Authentication.

    2. In the left navigation bar, click Auth Provider.

    3. Select Keycloak (SAML).

    4. Click Disable.

  3. Follow the steps in 在 Rancher 中配置 Keycloak.

    配置完成后，由于用户权限不会自动迁移，你需要重新申请 Rancher 用户权限。

附录：故障排除

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

所有与 Keycloak 相关的日志条目都将添加 [generic oidc] 或 [keycloak oidc]。

不能重定向到 Keycloak

完成配置 Keycloak OIDC 账号表单并单击启用后，你没有被重定向到你的 IdP。

验证你的 Keycloak 客户端配置。

生成的 Issuer 和 Auth 端点不正确

在配置 Keycloak OIDC 账号表单中，将端点更改为指定（高级设置）并覆盖发行者 和 Auth 端点的值。要查找这些值，前往 Keycloak 控制台并选择 Realm Settings，选择 General 选项卡，然后单击 OpenID Endpoint Configuration。JSON 输出将显示 issuer 和 authorization_endpoint 的值。

Keycloak 错误："Invalid grant_type"

在某些情况下，这条错误提示信息可能有误导性，实际上造成错误的原因是 Valid Redirect URI 配置错误。

Unable to See Groups When Assigning Global Roles

If you use a user that is not part of any groups for initial setup, then you cannot search for groups when trying to assign a global role. To resolve this, you can either:

  1. Manually edit the authconfig/keycloakoidc object to enable group search.

    1. On the Rancher server:

        kubectl edit authconfigs.management.cattle.io keycloakoidc

    2. Set groupSearchEnabled: true.

    3. Save your changes.

  2. Reconfigure your Keycloak OIDC setup using a user that is assigned to at least one group in Keycloak.

Configuring OIDC Single Logout (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'