跳至主要内容

將 Rancher 設定為 OIDC 提供者

Rancher 可以作為標準的 OpenID Connect (OIDC) 提供者，允許外部應用程式使用 Rancher 進行身份驗證。 這可用於在 Rancher Prime 元件之間啟用單一登入 (SSO)。例如，請參閱為 SUSE Observability 設定 OIDC 提供者的文件。

OIDC 提供者可以使用 oidc-provider 功能旗標啟用。當此旗標開啟時，以下端點可用：

  • https://{rancher-url}/oidc/authorize：此端點啟動身份驗證流程。如果使用者已登入 Rancher，它會返回授權碼。否則，它會將使用者重新導向到 Rancher 登入頁面。授權碼和相關請求資訊會安全地儲存在 session secrets 中。授權碼僅限一次使用，並在 10 分鐘後過期。

  • https://{rancher-url}/oidc/token：此端點將授權碼交換為 id_token、access_token 和 refresh_token。

  • https://{rancher-url}/oidc/.well-known/openid-configuration：此端點返回包含 OIDC 提供者設定的 JSON 文件，包括端點 URL、支援的範圍、聲明和其他相關詳細資訊。

  • https://{rancher-url}/oidc/userinfo：此端點提供有關已驗證使用者的資訊。

OIDC 提供者支援帶有 PKCE 的 OIDC 身份驗證碼流程。

設定 OIDCClient​

OIDCClient 代表將針對 Rancher 進行身份驗證的外部應用程式。

以程式化方式​

建立 OIDCClient：

apiVersion: management.cattle.io/v3
kind: OIDCClient
metadata:
  name: oidc-client-test
spec:
  tokenExpirationSeconds: 600 # expiration of the id_token and access_token
  refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token
  redirectURIs:
    - "https://myredirecturl.com" # replace with your redirect url

Rancher 會自動為每個 OIDCClient 生成用戶端 ID 和用戶端密碼。 建立資源後，Rancher 會使用用戶端 ID 填充狀態欄位：

apiVersion: management.cattle.io/v3
kind: OIDCClient
metadata:
  name: oidc-client-test
spec:
  tokenExpirationSeconds: 600 # expiration of the id_token and access_token
  refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token
  redirectURIs:
    - "https://myredirecturl.com" # replace with your redirect url
status:
  clientID: client-xxx
  clientSecrets:
    client-secret-1:
      createdAt: "xxx"
      lastFiveCharacters: xxx

Rancher 會自動為每個 OIDCClient 資源在 cattle-oidc-client-secrets 命名空間中生成 Kubernetes Secret。Secret 的名稱與 OIDCClient 用戶端 ID 相符。 最初，Secret 包含單個用戶端密碼。

要檢索用戶端密碼：

kubectl get secret client-xxx -n cattle-oidc-client-secrets -o jsonpath="{.data.client-secret-1}" | base64 -d

輸出：

secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

您現在可以在 OIDC 用戶端應用程式中使用此用戶端 ID 和用戶端密碼。

管理用戶端密碼​

您可以為每個 OIDCClient 管理多個用戶端密碼。在 OIDCClient 資源上使用註解來執行密碼操作：

  • 建立：新增 cattle.io/oidc-client-secret-create: true 註解會觸發建立新的用戶端密碼。
  • 移除：新增 cattle.io/oidc-client-secret-remove:client-secret-1 註解會移除指定的用戶端密碼。
  • 重新生成：新增 cattle.io/oidc-client-secret-regenerate:client-secret-1 註解會重新生成指定的用戶端密碼。

Rancher UI​

建立 OIDCClient：

  1. 在左上角，點擊 ☰ > 使用者與身份驗證。
  2. 在左側導覽選單中，點擊 OIDC Apps。
  3. 點擊 Add Application。填寫 Create OIDC App 表單。
  4. 點擊 Add Application。

管理用戶端密碼​

在 OIDC App 頁面中：

  • 建立：點擊 Add new secret。
  • 移除：點擊 ⋮ > Delete
  • 重新生成：點擊 ⋮ > Regenerate

簽署金鑰​

Rancher 會在 cattle-system 命名空間中名為 oidc-signing-key 的 Secret 中建立用於簽署 id_token、access_token 和 refresh_token 權杖的預設金鑰對。只有一個金鑰會用於簽署，但可以在 jwks 端點中返回多個公鑰，以避免在進行金鑰輪換時造成中斷。

無中斷輪換​

為了建立用於簽署的新金鑰對，您需要手動建立新的金鑰對並將其新增到 oidc-signing-key Secret 中

範例：

apiVersion: v1
kind: Secret
metadata:
 name: oidc-signing-key
type: Opaque
data:
 key2.pem: <base64-encoded-new-private-key>
 key1.pub: <base64-encoded-old-public-key>
 key2.pub: <base64-encoded-new-public-key>

Rancher 將使用 key2.pem 簽署權杖，而 JWKS 端點將同時提供 key1.pub 和 key2.pub。這確保了從 key1 到 key2 的平穩金鑰輪換，而不會中斷現有的權杖驗證。請注意，一次只能在 secret 中儲存一個私鑰 (.pem)，並且每個金鑰對必須共享相同的基本名稱，僅透過後綴區分：.pem 代表私鑰，.pub 代表公鑰。

有中斷的輪換​

移除 oidc-signing-key Secret 將導致 Rancher 在下次重新啟動時重新生成簽署金鑰。

注意

這將使所有先前發行的 id_token、access_token 和 refresh_token 權杖失效，使其無法使用。