設定機群成員叢集，以進行 OIDC 驗證

本文說明叢集管理員或應用程式運算子如何設定叢集，以支援使用第三方 OpenID Connect (OIDC) 提供者進行驗證。

限制

您必須使用支援 OIDC 的叢集類型。

事前準備

  1. Install the Google Cloud CLI.

  2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  3. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  4. 初始化 gcloud CLI 後，請更新 gcloud CLI 並安裝必要元件：

    gcloud components update
gcloud components install kubectl
  5. 請確認平台管理員已提供所有必要的供應商資訊。詳情請參閱「分享身分識別提供者詳細資料」。
  6. 如要使用 Google Cloud 控制台進行驗證，請向專案機群註冊要設定的每個叢集。詳情請參閱「車隊建立總覽」。
  7. 如要透過中繼主機連至目前虛擬私有雲網路外部的 AWS 或 Azure 叢集控制平面，請務必建立中繼主機，並在連接埠 8118 啟動 SSH 通道。在本文件中執行 kubectl 指令時，請在指令前加上 HTTPS_PROXY=http://localhost:PORT，其中 PORT 是您啟動 SSH 通道時使用的通訊埠號碼。
  8. 如果是 Google Cloud上的 GKE 叢集，請將叢集註冊至機群。

設定叢集

如要使用 OIDC 設定叢集的驗證，請將下列資訊新增至名為 ClientConfig 的 Kubernetes 自訂資源：

  • 身分識別提供者資訊，例如用戶端 ID 和密碼。
  • 身分識別提供者用於驗證的 JSON Web Token (JWT) 相關資訊。
  • 專屬於您身分識別提供者的任何其他範圍或參數。

如要進一步瞭解您需要向平台管理員或貴機構的身分管理員索取哪些資訊，請參閱「分享身分識別提供者詳細資料」。

叢集會使用 ClientConfig 自訂資源中的欄位，與您的身分識別提供者互動。每個叢集在 kube-public 命名空間中都有名為 default 的 ClientConfig。您修改的特定欄位取決於識別資訊提供者。

如要編輯 default ClientConfig，請確認您可以連線至叢集 kubectl，然後執行下列指令：

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

將 KUBECONFIG_PATH 替換為叢集 kubeconfig 檔案的路徑，例如 $HOME/.kube/config。

文字編輯器會載入叢集的 ClientConfig 資源。新增 spec.authentication.oidc 物件，如下列範例所示。請勿修改任何已寫入的預設資料。

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_AUTHORITY_DATA
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL
# Rest of the resource is managed by Google. DO NOT MODIFY.

舉例來說，請考量下列 ID 權杖欄位：

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  # Multiple lines are omitted here
}

在這個範例中，iss 是身分識別提供者 URI，sub 會識別使用者， 而 groupList 則會列出使用者所屬的安全群組。這個範例僅顯示實際權杖可能擁有的部分欄位。

以上述範例權杖為例，您可以在 ClientConfig 的 spec.authentication.oidc 物件中更新下列欄位：

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here

您可以在同一個 ClientConfig 中新增多個 OIDC、LDAP 和 SAML 識別資訊提供者設定。叢集會依定義順序，嘗試使用每項設定進行驗證，並在首次驗證成功後停止。以下 ClientConfig 範例會依特定順序定義多個身分識別提供者：

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here.

ClientConfig OIDC 欄位

下表說明 ClientConfig oidc 物件的欄位。您需要新增的欄位取決於識別資訊提供者權杖，以及平台管理員設定提供者的方式。

欄位 必填 說明 格式
名稱 是 您要用來識別這項設定的名稱，通常是身分識別提供者名稱。設定名稱開頭須為英文字母，其後最多可接 39 個小寫英文字母、數字或連字號，但結尾不得為連字號。 字串
certificateAuthorityData 否 身分識別提供者的 PEM 編碼憑證字串 (由平台管理員提供)。並把產生的字串另列一行加入 certificateAuthorityData。 字串
clientID 是 識別資訊提供者的用戶端 ID。 字串
clientSecret 否 OIDC 用戶端應用程式與 OIDC 供應商之間共用的密鑰。 字串
deployCloudConsoleProxy 否 指定是否部署 Proxy，讓 Google Cloud 控制台連線至無法透過網際網路公開存取的內部部署身分識別提供者。預設值為 false。 布林值
extraParams 否 要傳送至身分識別提供者的其他 key=value 參數，以逗號分隔的清單形式指定，例如 `prompt=consent,access_type=offline`。 以半形逗號分隔的清單
groupsClaim 否 供應商用來傳回帳戶安全性群組的 JWT 憑證附加資訊 (欄位名稱)。 字串
groupPrefix 否 如有多個身分識別提供者 (通常是提供者名稱) 的設定，請在安全群組名稱前方加上前置字串，以免與存取控制規則中的現有名稱衝突。 字串
issuerURI 是 向識別資訊提供者提出授權要求的 URI。URI 必須使用 HTTPS，且結尾不得為正斜線。 網址字串
kubectlRedirectURI 是 gcloud CLI 使用的重新導向網址和通訊埠，通常是平台管理員在註冊時指定，格式為 http://localhost:PORT/callback。 網址字串
範圍 是 要傳送給 OpenID 供應商的其他範圍。舉例來說，Microsoft Azure 和 Okta 需要 offline_access 範圍。 以半形逗號分隔的清單
userClaim 否 供應商用來識別使用者帳戶的 JWT 憑證附加資訊 (欄位名稱)。如未在此指定值，預設值為「sub」，這是許多供應商使用的使用者 ID 聲明。視 OpenID 供應商而定，您可以選擇其他憑證附加資訊，例如「電子郵件地址」或「姓名」。電子郵件地址以外的憑證附加資訊都必須在前方加上核發者網址，以免發生命名衝突。 字串
userPrefix 否 如不想使用預設前置字串，請輸入要加在使用者憑證附加資訊前方的字串，避免與現有名稱衝突。 字串
enableAccessToken 否 啟用後，當使用者從指令列登入時，叢集可以使用身分識別提供者的使用者資訊端點來取得群組資訊。如果您有提供者 (例如 Okta) 會從這個端點提供群組憑證附加資訊，這樣就能使用安全性群組進行授權。如未設定，系統會視為 false。 布林值
proxy 否 用於連線至身分識別供應商的 Proxy 伺服器位址 (如適用)，舉例來說，如果叢集位於私人網路中，且需要連線至公開身分識別提供者，您可能就需要設定這項功能。例如 http://user:password@10.10.10.10:8888。 字串

編輯 ClientConfig 後，請儲存檔案，更新叢集的 ClientConfig。如果發生任何語法錯誤，系統會提示您修正錯誤並儲存檔案。

供應商專屬設定

本節提供一些常見 OIDC 供應商的設定指引，包括可複製並以您自己的詳細資料編輯的設定範例。

Microsoft Entra ID

這是預設設定，可設定叢集以透過 Microsoft Entra ID 進行驗證。使用這項設定後，叢集就能從 Microsoft Entra ID 取得使用者和群組成員資格資訊，並根據群組設定 Kubernetes 角色型存取控制 (RBAC)。不過，使用這項設定時，每位使用者只能擷取約 200 個群組。

如需為每位使用者擷取超過 200 個群組，請參閱 Microsoft Entra ID (進階) 的操作說明。

# Multiple lines are omitted here.
spec:
  authentication:
  - name: oidc-entraid
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

更改下列內容：

  • CLIENT_ID：Microsoft Entra ID 中的用戶端 ID。
  • CLIENT_SECRET：OIDC 用戶端應用程式與 OIDC 提供者之間共用的密鑰。
  • TENANT_ID：要驗證的 Microsoft Entra ID 帳戶類型。如果帳戶隸屬於某個用戶群，支援的值則為用戶群 ID 或用戶群名稱。租戶名稱也稱為主網域。如要瞭解如何找出這些值，請參閱「找出 Microsoft Entra 租戶 ID 和主要網域名稱」。
  • PORT：平台管理員在註冊時指定，供 gcloud CLI 使用的重新導向網址所選用的連接埠號碼。

Microsoft Entra ID (進階)

這項 Microsoft Entra ID 選用設定可讓叢集使用 Microsoft Graph API 擷取使用者和群組資訊，且每位使用者的群組數量不受限制。

如要瞭解支援這項設定的平台，請參閱「Microsoft Entra ID 進階設定」。

如果每位使用者需要擷取的群組少於 200 個，建議您使用 ClientConfig 中的 oidc 錨點，採用預設設定。詳情請參閱 Microsoft Entra ID 的操作說明。

以下範例設定中的所有欄位皆為必填。

# Multiple lines are omitted here.
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM
# Multiple lines are omitted here. Do not modify any pre-filled data.

更改下列內容：

  • NAME：您要用來識別這項設定的名稱，通常是身分識別提供者名稱。設定名稱開頭須為英文字母，其後最多可接 39 個小寫英文字母、數字或連字號，但結尾不得為連字號。
  • PROXY_URL：用來連線至身分提供者的 Proxy 伺服器位址 (如適用)。舉例來說，如果叢集位於私人網路中，且需要連線至公開身分識別提供者，您可能就需要設定這項功能。例如：http://user:password@10.10.10.10:8888。
  • CLIENT_ID：Microsoft Entra ID 中的用戶端 ID。
  • CLIENT_SECRET：OIDC 用戶端應用程式與 OIDC 提供者之間共用的密鑰。
  • TENANT：要驗證的 Microsoft Entra 帳戶類型。如果帳戶隸屬於某個用戶群，支援的值則為用戶群 ID 或用戶群名稱。租戶名稱也稱為主網域。如要瞭解如何找出這些值，請參閱「找出 Microsoft Entra 租戶 ID 和主要網域名稱」。
  • PORT：平台管理員在註冊時指定，供 gcloud CLI 使用的重新導向網址所選用的連接埠號碼。
  • GROUP_FORMAT：您要擷取群組資訊的格式。這個欄位可以採用與使用者群組的 ID 或 NAME 相對應的值。請注意，這項設定僅適用於裸機 Google Distributed Cloud 部署作業中的叢集。
  • USER_CLAIM (選用)：供應商用來識別帳戶的 JWT 憑證附加資訊 (欄位名稱)。如果未在此指定值，叢集會依序使用「email」、「preferred_username」或「sub」中的值，擷取使用者詳細資料。這項屬性適用於 1.28 以上版本。

Okta

以下說明如何使用使用者和群組設定驗證，並以 Okta 做為身分識別提供者。這個設定可讓叢集使用存取權杖和 Okta 的 userinfo 端點，擷取使用者和群組憑證附加資訊。

# Multiple lines are omitted here.
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

群組存取權限制

對於 Okta 使用者，如果群組名稱串連後的長度少於 170000 個字元，叢集就能擷取這些使用者的群組資訊。根據 Okta 的群組長度上限，這大約對應 650 個群組的成員資格。如果使用者加入過多群組，驗證呼叫就會失敗。

後續步驟

套用設定後，請繼續設定叢集的使用者存取權。