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

配置通用 OIDC

通用 OpenID Connect (OIDC) 允许用户使用他们在 OIDC 身份提供者 (IdP) 上的现有账户凭据登录 Rancher。Rancher 支持与 OIDC 协议和 SAML 协议的集成。在与 Rancher 一起使用时，这两种实现功能上是等效的。以下说明描述了如何创建 OIDC 客户端并配置 Rancher 以与您的身份验证提供者一起使用。用户可以使用 OIDC IdP 的登录信息登录 Rancher。

先决条件

身份提供者

在 Rancher 中，通用 OIDC 是禁用的。

请查阅您特定 IdP 的文档以完成列出的先决条件。

OIDC 客户端

在您的 IdP 中，使用以下设置创建一个新客户端：

设置值

设置	值
`Client ID`	(例如 `rancher`)
`Name`	(例如 `rancher`)
`Client Protocol`	`openid-connect`
`Access Type`	`confidential`
`Valid Redirect URI`	`https://yourRancherHostURL/verify-auth`

Client ID

(例如 rancher)

Name

(例如 rancher)

Client Protocol

openid-connect

Access Type

confidential

Valid Redirect URI

https://yourRancherHostURL/verify-auth

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

由您在身份提供者的 OIDC 客户端中创建的组和组路径映射器生成的 groups 和 full_group_path 声明应为 JSON 数组，例如 "groups":["admins","devs","qa"] 和 "full_group_path":["/admins","/devs","/qa"]。

使用以下设置创建一个新的 Groups Mapper：

设置值

Name

Groups Mapper

Mapper Type

Group Membership

Token Claim Name

groups

Add to ID token

OFF

Add to access token

OFF

Add to user info

ON
使用以下设置创建一个新的 Client Audience：

设置值

Name

Client Audience

Mapper Type

Audience

Included Client Audience

Add to access token

ON
使用以下设置创建一个新的 Groups Path。

设置值

Name

Group Path

Mapper Type

Group Membership

Token Claim Name

full_group_path

Full group path

ON

Add to user info

ON

设置	值
`Name`	`Groups Mapper`
`Mapper Type`	`Group Membership`
`Token Claim Name`	`groups`
`Add to ID token`	`OFF`
`Add to access token`	`OFF`
`Add to user info`	`ON`

设置	值
`Name`	`Client Audience`
`Mapper Type`	`Audience`
`Included Client Audience`
`Add to access token`	`ON`

设置	值
`Name`	`Group Path`
`Mapper Type`	`Group Membership`
`Token Claim Name`	`full_group_path`
`Full group path`	`ON`
`Add to user info`	`ON`

Rancher 使用在 "sub" 声明中接收到的值来形成 PrincipalID，这是 Rancher 中的唯一标识符。重要的是，使该值唯一且不可变。

在 Rancher 中配置通用 OIDC

在 Rancher UI 的左上角，点击 ☰ > 用户与身份验证。
在左侧导航栏中，点击 身份验证提供者。
选择 通用 OIDC。
填写 配置 OIDC 账户 表单。有关填写表单的帮助，请参见配置参考。
单击启用。

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

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

*结果：*Rancher 已配置为使用 OIDC 协议与您的身份验证提供者配合工作。您的用户现在可以使用他们的 IdP 登录信息登录 Rancher。

自定义声明映射

在通用 OIDC 配置中支持自定义声明映射，适用于 name、email 和 groups 声明。这使您能够在IdP未在词元中使用标准名称时手动映射这些OIDC声明。

自定义组声明的工作原理

自定义组声明影响用户组的工作方式：

如果用户的词元中同时存在标准OIDC groups 声明和自定义组声明，则自定义声明补充标准声明提供的组列表。
如果词元中没有标准组声明，则自定义声明中列出的组将构成用户的唯一组。

对于来自自定义声明的组，没有可用的搜索功能。要将角色分配给这些组之一，您必须手动输入该组的确切名称到RBAC字段中。

配置自定义声明

在 配置 OIDC 账户 表单上：

选择*添加自定义声明*。
将您的自定义`name`、`email`或`groups`声明添加到适当的*自定义声明*字段中。

例如，如果您的 IdP 在名为 groups 的声明中发送 custom_roles，请在 自定义组声明 字段中输入 custom_roles。然后，Rancher 会补充标准 OIDC groups 声明，或在处理用户的词元时查找该特定声明。

配置参考

字段	说明
客户机 ID	您的 OIDC 客户端的客户端 ID。
客户端密钥	您的 OIDC 客户端生成的密钥。
私钥/证书	用于在Rancher和您的IdP之间创建安全外壳的密钥/证书对。如果在您的OIDC服务器上启用了HTTPS/SSL，则需要此项。
端点	选择是否使用生成的值填充Rancher URL、Issue和Auth Endpoint字段，或在不正确时提供手动覆盖。
Rancher URL	您的 Rancher 服务器的 URL。
颁发者	您的 IdP 的 URL。如果您的提供者启用了发现，Rancher 将使用发行者 URL 获取所有所需的 URL。
Auth Endpoint	用户被重定向到进行身份验证的 URL。

字段

说明

客户机 ID

您的 OIDC 客户端的客户端 ID。

客户端密钥

您的 OIDC 客户端生成的密钥。

私钥/证书

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

端点

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

Rancher URL

您的 Rancher 服务器的 URL。

颁发者

您的 IdP 的 URL。如果您的提供者启用了发现，Rancher 将使用发行者 URL 获取所有所需的 URL。

Auth Endpoint

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

自定义声明

自定义声明字段默认 OIDC 声明自定义声明描述

自定义声明字段	默认 OIDC 声明	自定义声明描述
自定义名称声明	`name`	OIDC 词元中包含用户全名或显示名称的声明名称。
自定义电子邮件声明	`email`	OIDC 词元中包含用户电子邮件地址的声明名称。
自定义组声明	`groups`	OIDC 词元中包含用户组成员资格（用于 RBAC）的声明名称。

自定义名称声明

name

OIDC 词元中包含用户全名或显示名称的声明名称。

自定义电子邮件声明

email

OIDC 词元中包含用户电子邮件地址的声明名称。

自定义组声明

groups

OIDC 词元中包含用户组成员资格（用于 RBAC）的声明名称。

OIDC 对 PKCE 扩展的支持

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.

查错

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

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

您没有被重定向到身份验证提供者

如果您填写了 配置通用 OIDC 账户 表单并点击启用，但没有被重定向到您的 IdP，请验证您的 OIDC 客户端配置。

生成的 `Issuer` 和 `Auth Endpoint` 不正确

如果 Issuer 和 Auth Endpoint 生成不正确，请打开 配置 OIDC 账户 表单，将端点更改为 Specify (advanced) 并覆盖 Issuer 值。

错误："无效的 grant_type"

在某些情况下，"无效的 grant_type" 错误消息可能会误导，实际上是由于错误地设置了 Valid Redirect URI。

配置 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.

Sign in to Rancher using a standard user or an administrator role.
In the top left corner, select ☰ > Users & Authentication.
In the left navigation menu, select Auth Provider.

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.

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.

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:

Obtain the Discovery URL by appending the IdP Issuer URL with the well-known path (.well-known/openid-configuration).
Send an HTTP GET request to the Discovery URL.
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'
```