設定 Keycloak (OIDC)

如果您的組織使用 Keycloak Identity Provider (IdP) 進行使用者身份驗證,您可以設定 Rancher 以允許您的使用者使用他們的 IdP 憑證登入。Rancher 支援使用 OpenID Connect (OIDC) 協定和 SAML 協定與 Keycloak 整合。在與 Rancher 配合使用時,兩種實作在功能上是等效的。本頁面描述使用 OIDC 協定設定 Rancher 與 Keycloak 配合使用的流程。

如果您更喜歡使用 SAML 協定的 Keycloak,請參閱此頁面。

如果您有使用 SAML 協定的現有設定並想要切換到 OIDC 協定,請參閱本節。

前置需求

• 在 Rancher 上,Keycloak (SAML) 已停用。

• 您必須設定好 Keycloak IdP Server。

• 按照 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 客戶端中,建立 Mappers 以公開使用者欄位。

  1. 在導覽選單中,點擊 Clients。
  2. 點擊 Clients list 分頁。
  3. 找到並點擊您建立的客戶端。
  4. 點擊 Client scopes 分頁。
  5. 找到並點擊標記為 <client-name>-dedicated 的連結。例如,如果您將客戶端命名為 rancher,請查找名為 rancher-dedicated 的連結。
  6. 點擊 Mappers 分頁。
  7. 點擊 Configure a new mapper。如果您已經設定了現有的映射器,請點擊 Add mapper 旁邊的箭頭並選擇 By configuration。重複此流程並建立這些映射器:

     • 從映射表中,選擇 Group Membership 並使用以下設定設定新的 "Groups Mapper"。對於未提及的設定,請使用預設值。

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

     • 從映射表中,選擇 Audience 並使用以下設定設定新的 "Client Audience"。對於未提及的設定,請使用預設值。

       設定	值
       Name	Client Audience
       Mapper Type	Audience
       Included Client Audience	<client-name>
       Add to ID token	OFF
       Add to access token	ON

     • 從映射表中,選擇 Group Membership 並使用以下設定設定新的 "Groups Path"。對於未提及的設定,請使用預設值。

       設定	值
       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 使用者的使用者或群組。

Users

1. 在導覽選單中,點擊 Users。
2. 點擊您想要新增角色映射的使用者。
3. 點擊 Role mapping 分頁。
4. 點擊 Assign role。
5. 選擇以下角色:
   • query-users
   • query-groups
   • view-users
6. 點擊 Assign。

Groups

1. 在導覽選單中,點擊 Groups。
2. 點擊您想要新增角色映射的群組。
3. 點擊 Role mapping 分頁。
4. 點擊 Assign role。
5. 選擇以下角色:
   • query-users
   • query-groups
   • view-users
6. 點擊 Assign。

在 Rancher 中設定 Keycloak

1. 在 Rancher UI 中,點擊 ☰ > Users & Authentication。

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

3. 選擇 Keycloak (OIDC)。

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

   備註

   使用 Generate 選項設定 Endpoints 部分時,Rancher 在 Issuer 和 Auth Endpoint 欄位中包含 /auth 作為上下文路徑的一部分,這僅對 Keycloak 16 或更舊版本有效。您必須使用 Specify 選項為 Keycloak 17 和更新版本設定端點,這些版本已遷移到 Quarkus。

5. 完成 Configure a Keycloak OIDC account 表單後,點擊 Enable。

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

   備註

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

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

SAML 提供者注意事項

• 在 Rancher 中為使用者和群組分配權限時,不會驗證它們。
• 新增使用者時,必須正確輸入確切的使用者 ID(即 UID Field)。當您輸入使用者 ID 時,不會搜尋其他可能匹配的使用者 ID。
• 新增群組時,您必須從文字方塊旁邊的下拉式選單中選擇群組。Rancher 假設來自文字方塊的任何輸入都是使用者。
• 群組下拉式選單僅顯示您所屬的群組。但是,如果您擁有管理員權限或受限管理員權限,您可以加入您不是成員的群組。

設定參考

欄位	描述
Client ID	您的 Keycloak 客戶端的 Client ID。
Client Secret	您的 Keycloak 客戶端生成的 Secret。在 Keycloak 控制台中,選擇 Clients,選擇您建立的客戶端,選擇 Credentials 分頁並複製 Secret 欄位的值。
Private Key / Certificate	用於在 Rancher 和您的 IdP 之間建立安全 shell 的金鑰/憑證對。如果您的 Keycloak 伺服器上啟用了 HTTPS/SSL,則為必需。
Endpoints	選擇是使用 Rancher URL、Issue 和 Auth Endpoint 欄位的生成值還是在不正確時提供手動覆寫。
Keycloak URL	您的 Keycloak 伺服器的 URL。
Keycloak Realm	建立 Keycloak 客戶端的 realm 的名稱。
Rancher URL	您的 Rancher Server 的 URL。
Issuer	您的 IdP 的 URL。
Auth Endpoint	使用者被重新導向以進行身份驗證的 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 中,點擊 ☰ > Users & Authentication。
   2. 在左側導覽列中,點擊 Auth Provider。
   3. 選擇 Keycloak (SAML)。
   4. 點擊 Disable。
3. 按照在 Rancher 中設定 Keycloak 中的步驟操作。

警告

完成設定後,需要重新套用 Rancher 使用者權限,因為它們不會自動遷移。

附錄:疑難排解

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

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

您未被重新導向至 Keycloak

當您填寫 Configure a Keycloak OIDC account 表單並點擊 Enable 時,您未被重新導向至 IdP。

驗證您的 Keycloak 客戶端設定。

生成的 Issuer 和 Auth Endpoint 不正確

在 Configure a Keycloak OIDC account 表單上,將 Endpoints 更改為 Specify (advanced) 並覆寫 Issuer 和 Auth Endpoint 值。要找到這些值,請前往 Keycloak 控制台並選擇 Realm Settings,選擇 General 分頁,然後點擊 OpenID Endpoint Configuration。JSON 輸出顯示 issuer 和 authorization_endpoint 的值。

Keycloak 錯誤: "Invalid 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 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 提供者。