為 OIDC 驗證設定機群成員叢集

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

限制

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

事前準備

  1. 安裝 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. 如果是 GKE 叢集，請 Google Cloud將叢集註冊至機群。

設定叢集

如要使用 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 提供者而定，您可以選擇其他憑證附加資訊，例如「電子郵件」或「名稱」。「email」以外的憑證附加資訊會加上核發者網址前置字串，以免名稱衝突。 字串
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 的使用者資訊端點，擷取使用者和群組憑證附加資訊。

# 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 個群組的成員資格。如果使用者加入過多群組，驗證呼叫就會失敗。

後續步驟

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