跳至主要内容

設定 Keycloak (SAML)

如果您的組織使用 Keycloak Identity Provider (IdP) 進行使用者身份驗證,您可以設定 Rancher 以允許您的使用者使用他們的 IdP 憑證登入。

前置需求​

  • 您必須設定好 Keycloak IdP Server。

  • 在 Keycloak 中,使用以下設定建立新的 SAML 客戶端。請參閱 Keycloak 文件以取得協助。

    設定值
    Sign DocumentsON 1
    Sign AssertionsON 1
    所有其他 ON/OFF 設定OFF
    Client ID要麼是 https://yourRancherHostURL/v1-saml/keycloak/saml/metadata 要麼是 Rancher Keycloak 設定的 Entry ID Field 中設定的值2
    Client Name<CLIENT_NAME> (例如 rancher)
    Client ProtocolSAML
    Valid Redirect URIhttps://yourRancherHostURL/v1-saml/keycloak/saml/acs

    1: 選擇性地,您可以啟用這些設定中的一個或兩個。 2: Rancher SAML 元資料在設定並儲存 SAML 提供者之前不會生成。

  • 在新的 SAML 客戶端中,建立 Mappers 以公開使用者欄位

    • 新增所有 "Builtin Protocol Mappers"
    • 建立新的 "Group list" 映射器以將 member 屬性對應到使用者的群組

取得 IDP 元資料​

要取得 IDP 元資料,請從您的 Keycloak 客戶端匯出 metadata.xml 檔案。 從 Installation 分頁中,選擇 SAML Metadata IDPSSODescriptor 格式選項並下載您的檔案。

在 Rancher 中設定 Keycloak​

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

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

  3. 點擊 Keycloak SAML。

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

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

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

    備註

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

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

SAML 提供者注意事項:
  • SAML 協定不支援搜尋或查找使用者或群組。因此,在將使用者或群組新增到 Rancher 時不會進行驗證。
  • 新增使用者時,必須正確輸入確切的使用者 ID(即 UID Field)。當您輸入使用者 ID 時,不會搜尋其他可能匹配的使用者 ID。
  • 新增群組時,您必須從文字方塊旁邊的下拉式選單中選擇群組。Rancher 假設來自文字方塊的任何輸入都是使用者。
  • 群組下拉式選單僅顯示您所屬的群組。您將無法新增您不是成員的群組。

設定參考​

欄位描述
Display Name Field包含使用者顯示名稱的屬性。

範例:givenName
User Name Field包含使用者名稱/給定名稱的屬性。

範例:email
UID Field對每個使用者唯一的屬性。

範例:email
Groups Field用於管理群組成員資格的條目。

範例:member
Entity ID Field需要在 Keycloak 客戶端中設定為客戶端 ID 的 ID。

預設:https://yourRancherHostURL/v1-saml/keycloak/saml/metadata
Rancher API Host您的 Rancher Server 的 URL。
Private Key / Certificate用於在 Rancher 和您的 IdP 之間建立安全 shell 的金鑰/憑證對。
IDP-metadata您從 IdP 伺服器匯出的 metadata.xml 檔案。
提示

您可以使用 openssl 命令生成金鑰/憑證對。例如:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

附錄:疑難排解​

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

您未被重新導向至 Keycloak​

當您點擊 Authenticate with Keycloak 時,您未被重新導向至 IdP。

  • 驗證您的 Keycloak 客戶端設定。
  • 確保 Force Post Binding 設定為 OFF。

IdP 登入後顯示 Forbidden 訊息​

您被正確重新導向至 IdP 登入頁面,並且您能夠輸入憑證,但之後您收到 Forbidden 訊息。

  • 檢查 Rancher 除錯日誌。
  • 如果日誌顯示 ERROR: either the Response or Assertion must be signed,請確保在您的 Keycloak 客戶端中將 Sign Documents 或 Sign assertions 設定為 ON。

嘗試存取 /v1-saml/keycloak/saml/metadata 時出現 HTTP 502​

這通常是由於在設定 SAML 提供者之前不會建立元資料。 嘗試設定並儲存 keycloak 作為您的 SAML 提供者,然後存取元資料。

Keycloak 錯誤: "We're sorry, failed to process response"​

  • 檢查您的 Keycloak 日誌。
  • 如果日誌顯示 failed: org.keycloak.common.VerificationException: Client does not have a public key,請在您的 Keycloak 客戶端中將 Encrypt Assertions 設定為 OFF。

Keycloak 錯誤: "We're sorry, invalid requester"​

  • 檢查您的 Keycloak 日誌。
  • 如果日誌顯示 request validation failed: org.keycloak.common.VerificationException: SigAlg was null,請在您的 Keycloak 客戶端中將 Client Signature Required 設定為 OFF。

設定 SAML 單一登出 (SLO)​

備註

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

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

若要配置 SAML SLO：

  1. 在左上角，點選 ☰ > Users & Authentication。
  2. 在左側導覽選單中，點選 Auth Provider。
  3. 找到您的 SAML 提供者並點選 ⋮ > Edit Config。
  4. 在 Single Logout 下，勾選 Enabled 核取方塊。
  5. 在 Identity Provider Single Logout URL 欄位中，輸入您的身份提供者提供的單一登出 URL。
  6. 在 Rancher Single Logout URL 欄位中，輸入您的 Rancher 伺服器 URL，後面加上 /v1-saml/provider/saml/slo。例如：https://rancher.example.com/v1-saml/provider/saml/slo
  7. 點選 Save。

配置 SLO 後，您可能需要更新身份提供者的配置，以將 Rancher Single Logout URL 包含為有效的登出端點。

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