設定通用 OIDC

通用 OpenID Connect (OIDC) 允許使用者使用他們在 OIDC 身份提供者 (IdP) 的現有帳戶憑證登入 Rancher。Rancher 支援與 OIDC 協定和 SAML 協定的整合。在與 Rancher 配合使用時,兩種實作在功能上是等效的。以下說明描述如何建立 OIDC 客戶端並設定 Rancher 與您的身份驗證提供者配合使用。然後使用者可以使用 OIDC IdP 的登入資訊登入 Rancher。

前置需求

身份提供者

在 Rancher 中,通用 OIDC 已停用。

備註

請參閱您特定 IdP 的文件以完成列出的前置需求。

OIDC 客戶端

在您的 IdP 中,使用以下設定建立新客戶端:

設定	值
Client ID	<CLIENT_ID> (例如 rancher)
Name	<CLIENT_NAME> (例如 rancher)
Client Protocol	openid-connect
Access Type	confidential
Valid Redirect URI	https://yourRancherHostURL/verify-auth

在新的 OIDC 客戶端中,建立映射器以公開使用者的欄位。

1. 使用以下設定建立新的 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

1. 使用以下設定建立新的 Client Audience:

設定	值
Name	Client Audience
Mapper Type	Audience
Included Client Audience	CLIENT_NAME
Add to access token	ON

1. 使用以下設定建立新的 Groups Path。

設定	值
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

1. 在 Rancher UI 的左上角,點擊 ☰ > Users & Authentication。

2. 在左側導覽列中,點擊 Auth Provider。

3. 選擇 Generic OIDC。

4. 完成 Configure an OIDC account 表單。如需填寫表單的協助,請參閱設定參考。

5. 點擊 Enable。

   Rancher 會將您重新導向至 IdP 登入頁面。輸入您的 IdP 憑證以驗證您的 Rancher Keycloak 設定。

   備註

   您可能需要停用彈出視窗封鎖程式才能看到 IdP 登入頁面。

結果: Rancher 已設定為使用 OIDC 協定與您的提供者配合使用。您的使用者現在可以使用他們的 IdP 登入資訊登入 Rancher。

自訂聲明映射

通用 OIDC 設定中支援 name、email 和 groups 聲明的自訂聲明映射。這允許您在 IdP 不在權杖中使用標準名稱時手動映射這些 OIDC 聲明。

自訂群組聲明的運作方式

自訂群組聲明會影響使用者群組的運作方式:

• 如果使用者的權杖中同時存在標準 OIDC groups 聲明和自訂群組聲明,則自訂聲明會補充標準聲明提供的群組清單。
• 如果權杖中沒有標準群組聲明,則自訂聲明中列出的群組將形成使用者唯一的群組。

備註

來自自訂聲明的群組沒有可用的搜尋功能。要為這些群組之一分配角色,您必須在 RBAC 欄位中手動輸入群組的確切名稱。

設定自訂聲明

在 Configure an OIDC account 表單上時:

1. 選擇 Add custom claims。
2. 將您的自訂 name、email 或 groups 聲明新增到適當的 Custom Claims 欄位。

例如,如果您的 IdP 在名為 custom_roles 的聲明中發送 groups,請在 Custom Groups Claim 欄位中輸入 custom_roles。然後 Rancher 在處理使用者的權杖時會補充標準 OIDC groups 聲明或尋找該特定聲明。

設定參考

欄位	描述
Client ID	您的 OIDC 客戶端的 Client ID。
Client Secret	您的 OIDC 客戶端生成的 Secret。
Private Key/Certificate	用於在 Rancher 和您的 IdP 之間建立安全 shell 的金鑰/憑證對。如果您的 OIDC 伺服器上啟用了 HTTPS/SSL,則為必需。
Endpoints	選擇是使用 Rancher URL、Issue 和 Auth Endpoint 欄位的生成值還是在不正確時提供手動覆寫。
Rancher URL	您的 Rancher Server 的 URL。
Issuer	您的 IdP 的 URL。如果您的提供者啟用了發現功能,Rancher 會使用 Issuer URL 來取得所有必需的 URL。
Auth Endpoint	使用者被重新導向以進行身份驗證的 URL。

自訂聲明

自訂聲明欄位	預設 OIDC 聲明	自訂聲明描述
Custom Name Claim	name	OIDC 權杖中包含使用者全名或顯示名稱的聲明的名稱。
Custom Email Claim	email	OIDC 權杖中包含使用者電子郵件地址的聲明的名稱。
Custom Groups Claim	groups	OIDC 權杖中包含使用者群組成員資格(用於 RBAC)的聲明的名稱。

疑難排解

如果您在測試與 OIDC 伺服器的連線時遇到問題,請先仔細檢查 OIDC 客戶端的設定選項。您還可以檢查 Rancher 日誌以幫助找出導致問題的原因。除錯日誌可能包含有關錯誤的更詳細資訊。請參閱本文件中的如何啟用除錯日誌。

所有通用 OIDC 相關的日誌條目都以 [generic oidc] 或 [oidc] 為前綴。

您未被重新導向至身份驗證提供者

如果您填寫 Configure a Generic OIDC account 表單並點擊 Enable,但未被重新導向至 IdP,請驗證您的 OIDC 客戶端設定。

生成的 Issuer 和 Auth Endpoint 不正確

如果 Issuer 和 Auth Endpoint 生成不正確,請開啟 Configure an OIDC account 表單,將 Endpoints 更改為 Specify (advanced) 並覆寫 Issuer 值。

錯誤: "Invalid grant_type"

在某些情況下,"Invalid grant_type" 錯誤訊息可能具有誤導性,實際上是由於設定 Valid Redirect URI 不正確引起的。

設定 OIDC 單一登出 (SLO)

備註

此功能在 Rancher v2.7.2 及更高版本中可用。

單一登出（SLO）允許使用者在單一操作中登出所有應用程式。當您在 Rancher 中啟用 OIDC SLO 時，使用者可以同時登出 Rancher 和他們的 OIDC 提供者。

若要配置 OIDC SLO：

1. 在左上角，點選 ☰ > Users & Authentication。
2. 在左側導覽選單中，點選 Auth Provider。
3. 找到您的 OIDC 提供者並點選 ⋮ > Edit Config。
4. 在 Single Logout 下，勾選 Enabled 核取方塊。
5. 在 End Session Endpoint 欄位中，輸入您的 OIDC 提供者的結束會話端點 URL。此端點通常由您的 OIDC 提供者提供文件說明。
6. 點選 Save。

結果： 使用者現在可以透過點選他們的個人資料圖示並選擇 Log Out，同時登出 Rancher 和 OIDC 提供者。