使用外部識別資訊提供者向 GKE 進行驗證

自動駕駛 標準

---

本頁面說明如何設定驗證，從外部身分識別提供者 (IdP) 存取 Google Kubernetes Engine (GKE) 叢集。

本頁內容適用於平台管理員和營運人員，以及使用支援 OpenID Connect (OIDC) 或安全宣告標記語言 (SAML) 2.0 的外部 IdP 的身分和帳戶管理員。

閱讀本頁內容前，請務必熟悉下列驗證和 OpenID 概念：

• OAuth 2.0
• SAML 2.0
• OpenID Connect
• OIDC 範圍和聲明
• Kubernetes RBAC

GKE 中的外部 IdP 驗證方法

建議：員工身分聯盟

員工身分聯盟是 IAM 功能，可讓您從支援 OIDC 或 SAML 2.0 的任何外部 IdP 進行驗證。 Google Cloud 員工身分聯盟不需要在叢集中安裝任何項目，適用於 Autopilot 叢集和標準叢集，且內建於 Google Cloud。詳情請參閱身分與存取權管理說明文件中的「員工身分聯盟」。

不建議 - GKE 適用的 Identity 服務

只有在 GKE Standard 叢集中，GKE 也支援 GKE 適用的 Identity Service。GKE 適用的 Identity Service 僅限 OIDC IdP，且會在叢集中安裝其他元件。GKE 強烈建議使用 Workforce Identity Federation，而非 GKE 適用的 Identity Service。此外，請注意 GKE 適用的 Identity 服務有已知限制，會導致無法自動調度。

注意： 自 2025 年 7 月 1 日起，您建立的新 Google Cloud 機構將不支援 GKE 適用的 Identity 服務。

事前準備

開始之前，請確認您已完成下列工作：

• 啟用 Google Kubernetes Engine API。
啟用 Google Kubernetes Engine API
• 如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update，取得最新版本。
  注意：如果是現有的 gcloud CLI 安裝項目，請務必設定 compute/region 屬性。如果您主要使用區域叢集，請改為設定 compute/zone。設定預設位置後，即可避免 gcloud CLI 發生下列錯誤：One of [--zone, --region] must be supplied: Please specify location。如果叢集位置與您設定的預設位置不同，您可能需要在特定指令中指定位置。

注意事項

無論是員工身分聯盟或 GKE 適用的 Identity 服務，都不支援無頭系統。瀏覽器式驗證流程會提示您同意並授權使用者帳戶。

在 GKE 中使用員工身分聯盟

如要在 GKE 叢集中使用員工身分聯盟，請完成下列步驟：

1. 為貴機構和外部 IdP 設定員工身分聯盟。 如需操作說明，請參閱「設定員工身分聯盟」。
2. 從外部 IdP 設定對 Google Cloud 員工身分聯盟控制台的存取權。詳情請參閱「設定使用者對控制台 (聯合) 的存取權」。

3. 使用下列其中一種授權機制設定使用者存取權：

   • Kubernetes RBAC
   • 身分與存取權管理允許政策

4. 請要求使用者完成下列步驟，存取叢集：

   1. 使用聯合身分登入 gcloud CLI。
   2. 執行 gcloud container clusters get-credentials，設定 kubectl 對特定叢集進行驗證。

使用 RBAC 設定叢集的使用者存取權

Google Cloud 會使用主體 ID 識別工作團隊身分集區中的使用者。您可以在 Kubernetes RBAC 政策或 IAM 政策中參照這些主體 ID。您可以將權限授予個別使用者或使用者群組，例如：

身分識別	主體 ID
單一使用者	principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/subject/SUBJECT_ATTRIBUTE_VALUE 更改下列內容： WORKFORCE_IDENTITY_POOL：工作團隊身分集區的名稱。 SUBJECT_ATTRIBUTE_VALUE：身分權杖主體聲明中的屬性值。舉例來說，這可能是 SAML 2.0 判斷中的 NameID 欄位值。 例如： principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/[e-mail]
群組中的所有使用者	principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/group/GROUP_NAME 更改下列內容： WORKFORCE_IDENTITY_POOL：工作團隊身分集區的名稱。 GROUP_NAME：驗證使用者所屬群組的名稱。IdP 權杖中的聲明必須具有對應至 Google Cloud google.groups 屬性的屬性對應。 例如： principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre

如要瞭解員工身分聯盟支援的每個主體 ID，請參閱「在 IAM 政策中代表員工集區使用者」。

以下範例說明如何授予 Secrets 的叢集範圍唯讀存取權，給予 full-time-employees 工作人員集區中，屬於 IdP 權杖中 sre 群組的任何實體。

1. 請將下列 ClusterRole 資訊清單儲存為 secret-viewer-cluster-role.yaml：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: secret-viewer
   rules:
   - apiGroups: [""]
     resources: ["secrets"]
     verbs: ["get", "watch", "list"]
   

   您將這個 ClusterRole 繫結至任何主體後，該主體就能查看密鑰。

2. 將下列 ClusterRoleBinding 資訊清單儲存為 secret-viewer-cluster-role-binding.yaml：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name:  users-view-secrets
   subjects:
   - kind: Group
     name: principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     name: secret-viewer
     apiGroup: rbac.authorization.k8s.io
   

   這個 ClusterRoleBinding 會將 secret-viewer ClusterRole 授予 sre 群組中的任何使用者。

3. 部署 ClusterRole 和 ClusterRoleBinding：

   kubectl apply -f secret-viewer-cluster-role.yaml
   kubectl apply -f secret-viewer-cluster-role-binding.yaml
   

登入及驗證叢集

1. 請使用者使用 Google Cloud CLI 登入。 Google Cloud

2. 使用者可以透過下列方式，設定 kubectl 對叢集進行驗證：

   gcloud container clusters get-credentials
   

將 GKE 適用的 Identity Service 叢集遷移至員工身分聯盟

如果您在現有 GKE 叢集中使用 GKE 適用的 Identity 服務，請遷移至員工身分聯盟。這些方法會使用不同的語法參照相同主體，如下表所示：

GKE 適用的 Identity Service 語法	員工身分聯盟語法
[e-mail]	principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/[e-mail]
sre-group	principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre-group

如要將叢集遷移至使用員工身分聯盟，請按照下列步驟操作：

1. 為貴機構和外部 IdP 設定員工身分聯盟。 如需操作說明，請參閱「設定員工身分聯盟」。

2. 更新叢集中任何 RoleBinding 和 ClusterRoleBinding 的資訊清單，使用 Workforce Identity Federation 識別碼語法。請使用下列其中一種方式：

   • 程式輔助更新：安裝並執行 gke-identity-service-migrator 公用程式。如需操作說明，請參閱 GoogleCloudPlatform/gke-utilities 存放區 README。

     這項公用程式會找出使用 GKE Identity Service 語法的現有 RBAC 繫結，並建立使用對應 Workforce Identity Federation 主體 ID 的新資訊清單。

   • 手動更新：針對參照已驗證使用者或群組的每個繫結，建立物件資訊清單檔案的個別副本，並使用 Workforce Identity Federation 識別碼語法。

3. 將更新後的 RoleBinding 和 ClusterRoleBinding 資訊清單套用至叢集。

4. 測試使用者透過員工身分聯盟驗證身分時，是否能存取相同資源。

5. 從叢集中移除過時的 RBAC 繫結。

6. 停用 GKE 適用的 Identity Service。

使用 GKE 適用的 Identity Service

注意： 自 2025 年 7 月 1 日起，您建立的新 Google Cloud 機構將不支援 GKE 適用的 Identity 服務。

如要在 GKE Standard 模式叢集上設定及使用 GKE 適用的 Identity Service，叢集管理員請執行下列操作：

1. 在叢集上啟用 GKE Identity Service。
2. 為 GKE 設定 Identity Service。
3. 為叢集建立 RBAC 政策。

叢集管理員為 GKE 設定 Identity Service 後，開發人員即可登入叢集並通過驗證。

Identity Service for GKE 建立的 Kubernetes 物件

下表說明在叢集上啟用 GKE 適用的 Identity Service 時建立的 Kubernetes 物件：

Kubernetes 物件
anthos-identity-service	Namespace 用於 GKE 適用的 Identity Service 部署作業。
kube-public	Namespace 用於 default 用戶端設定檔。
gke-oidc-envoy	LoadBalancer OIDC 要求的端點。預設為外部。如果是在沒有外部 IP 端點的叢集中建立，端點會位於叢集虛擬私有雲內部。 在 anthos-identity-service 命名空間中建立。
gke-oidc-service	ClusterIP 促進 gke-oidc-envoy 部署作業與 gke-oidc-service 部署作業之間的通訊。 在 anthos-identity-service 命名空間中建立。
gke-oidc-envoy	Deployment 執行向 gke-oidc-envoy LoadBalancer 公開的 Proxy。與 gke-oidc-service 通訊，驗證身分識別權杖。做為 Kubernetes API 伺服器的 Proxy，並在將要求傳遞至 API 伺服器時模擬使用者。 在 anthos-identity-service 命名空間中建立。
gke-oidc-service	Deployment 驗證 ID 權杖，並為 ClientConfig 資源提供驗證許可控制器 Webhook。 在 anthos-identity-service 命名空間中建立。
gke-oidc-operator	Deployment 協調用戶端設定和 gke-oidc-envoy LoadBalancer。 在 anthos-identity-service 命名空間中建立。
gke-oidc-certs	Secret 包含叢集憑證授權單位 (CA) 和 LoadBalancer 的 TLS 憑證。 在 anthos-identity-service 命名空間中建立
default	ClientConfig CRD 包含 OIDC 參數，例如偏好的驗證方式、身分識別提供者設定，以及使用者和群組聲明對應。用於驗證 ID 權杖。叢集管理員可使用此檔案設定 OIDC 設定，然後再發布給開發人員。 在 kube-public 命名空間中建立

在叢集上啟用 GKE Identity Service

根據預設，Identity and Access Management (IAM) 是叢集驗證程序中的識別資訊提供者。如要透過第三方身分識別提供者使用 OIDC，您可以使用 Google Cloud CLI，在新叢集或現有叢集上啟用 GKE 適用的 Identity Service。

注意： 為確保 GKE Identity Service 正常運作，GKE 會將 Pod 部署至具有提升RBAC 權限的節點，例如模擬使用者和群組的能力。Identity Service for GKE 必須具備這些權限，才能根據您的設定進行身分驗證和通訊。

在新叢集上啟用 GKE Identity Service

如要建立啟用 GKE 適用的 Identity 服務的叢集，請執行下列指令：

gcloud container clusters create CLUSTER_NAME \
    --enable-identity-service

將 CLUSTER_NAME 替換為新叢集的名稱。

在現有叢集上啟用 GKE 專用的 Identity Service

如要在現有叢集上啟用 GKE 適用的 Identity Service，請執行下列指令

gcloud container clusters update CLUSTER_NAME \
    --enable-identity-service

將 CLUSTER_NAME 替換為叢集名稱。

設定 GKE 適用的 Identity Service

您可以下載並修改 default ClientConfig，設定 GKE 適用的 Identity 服務參數。

1. 下載 default ClientConfig：

   kubectl get clientconfig default -n kube-public -o yaml > client-config.yaml
   

2. 使用偏好設定更新 spec.authentication 區段：

   apiVersion: authentication.gke.io/v2alpha1
   kind: ClientConfig
   metadata:
     name: default
     namespace: kube-public
   spec:
     name: cluster-name
     server: https://192.168.0.1:6443
     authentication:
     - name: oidc
       oidc:
         clientID: CLIENT_ID
         certificateAuthorityData: OIDC_PROVIDER_CERTIFICATE
         extraParams: EXTRA_PARAMS
         issuerURI:  ISSUER_URI
         cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
         kubectlRedirectURI: KUBECTL_REDIRECT_URL
         scopes: SCOPES
         userClaim: USER
         groupsClaim: GROUPS
         userPrefix: USER_PREFIX
         groupPrefix: GROUP_PREFIX
   

   更改下列內容：

   • CLIENT_ID：向 OIDC 供應商提出驗證要求時使用的用戶端應用程式 ID。
   • OIDC_PROVIDER_CERTIFICATE：(選用) OIDC 供應商的 PEM 憑證。如果 OIDC 供應商使用自行簽署的憑證，這個欄位就非常實用。GKE 適用的 Identity Service 預設包含一組公開根憑證。
   • EXTRA_PARAMS：要傳送至 OIDC 提供者的其他鍵/值參數。
     • 如要授權群組，請使用 resource=token-groups-claim。
     • 如要驗證 Microsoft Azure 和 Okta，請使用 prompt=consent。
     • 如果是 Cloud Identity，請使用 prompt=consent,access_type=offline。
   • ISSUER_URI：用於傳送 OIDC 授權要求的網址，例如 https://example.com/adfs。Kubernetes API 伺服器會使用這個網址探索公開金鑰，以驗證權杖。URI 必須使用 HTTPS。如果是 Cloud Identity，請使用 https://accounts.google.com。
   • KUBECTL_REDIRECT_URL：kubectl oidc login 用於授權的重新導向網址。這通常採用 http://localhost:PORT/callback 格式，其中 PORT 是大於 1024 的任何連接埠，可在開發人員工作站上使用，例如 http://localhost:10000/callback。您必須向 OIDC 供應商註冊網址，做為用戶端應用程式的授權重新導向網址。如果您使用 Google Identity 做為 OIDC 提供者，請參閱「設定重新導向 URI」一文中的操作說明。
   • SCOPES：要傳送至 OIDC 提供者的其他範圍。
     • Microsoft Azure 和 Okta 需要 offline_access 範圍。
     • 如果是 Cloud Identity，請使用 openid, email 取得 ID 權杖，其中包含 email 聲明中的電子郵件地址。
   • USER：身分識別權杖中的使用者聲明。
   • GROUPS：身分識別權杖中的群組聲明。
   • USER_PREFIX：在使用者憑證附加資訊的前方加上此字串，可避免與現有的名稱衝突。根據預設，系統會將簽發者前置字串附加至提供給 Kubernetes API 伺服器的 userID (除非使用者聲明是 email)。產生的使用者 ID 為 ISSUER_URI#USER。建議使用前置字串，但您可以將 USER_PREFIX 設為 -，停用前置字串。
   • GROUP_PREFIX：在群組憑證附加資訊的前方加上此字串，即可避免與現有的名稱衝突。舉例來說，如果您有兩個名為 foobar 的群組，請加上前置字串 gid-。產生的群組為 gid-foobar。

3. 套用更新後的設定：

   kubectl apply -f client-config.yaml
   

   套用這項設定後，GKE Identity Service 會在叢集內執行，並在 gke-oidc-envoy 負載平衡器後方處理要求。「spec.server」欄位中的 IP 位址必須是負載平衡器的 IP 位址。如果變更 spec.server 欄位，kubectl 指令可能會失敗。

4. 複製 client-config.yaml 設定檔：

   cp client-config.yaml login-config.yaml
   

5. 在 spec.authentication.oidc 區段中，使用 clientSecret 設定更新 login-config.yaml 設定檔。

   clientSecret: CLIENT_SECRET
   

   將 CLIENT_SECRET 替換為 OIDC 用戶端應用程式與 OIDC 供應商之間共用的密鑰。

6. 將更新後的 login-config.yaml 檔案發送給開發人員。

在採用嚴格政策的叢集上設定 GKE 適用的 Identity 服務

如要設定 GKE 適用的 Identity Service，確保服務在設有嚴格網路政策的叢集上正常運作，請按照下列步驟操作：

1. 新增 TCP 通訊埠 15000 的防火牆規則，允許控制平面與 ClientConfig 驗證 Webhook 通訊。
2. 如果 gke-oidc-envoy 是以內部負載平衡器形式建立，請在 VPC 中公開該負載平衡器。
3. 如果您的政策會拒絕叢集內的流量，請新增 TCP 通訊埠 8443 的防火牆規則，允許 gke-oidc-envoy 部署作業與 gke-oidc-service 部署作業通訊。

GKE 專用 Identity Service 元件 0.2.20 以上版本不會使用 TCP 通訊埠 15000。如果元件版本為 0.2.20 以上，則不需要為連接埠 15000 新增防火牆規則。如要檢查元件版本，請執行下列指令：

kubectl describe deployment gke-oidc-envoy -n anthos-identity-service \
    | grep "components.gke.io/component-name: gke-oidc" -A1

在負載平衡器中新增自訂屬性

設定 GKE 適用的 Identity 服務後，您可以將靜態 IP 位址等自訂註解和屬性新增至 gke-oidc-envoy 負載平衡器。如要編輯 gke-oidc-envoy 服務，請執行下列指令：

kubectl edit service gke-oidc-envoy -n anthos-identity-service

如要進一步瞭解如何為 GKE 設定 TCP/UDP 負載平衡，請參閱「LoadBalancer 服務參數」。

為叢集建立 RBAC 政策

管理員可以使用 Kubernetes 角色式存取控管 (RBAC)，授予已通過驗證的叢集使用者存取權。如要為叢集設定 RBAC，您必須為每位開發人員授予 RBAC 角色。如要授予特定命名空間中資源的存取權，請建立角色和RoleBinding。如要授予整個叢集的資源存取權，請建立 ClusterRole 和 ClusterRoleBinding。

舉例來說，假設使用者需要查看叢集中的所有 Secret 物件，下列步驟會將必要的 RBAC 角色授予這位使用者。

1. 將下列 ClusterRole 資訊清單儲存為 secret-viewer-cluster-role.yaml。獲派這個角色的人員可以取得、監控及列出叢集中的任何密鑰。

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: secret-viewer
   rules:
   - apiGroups: [""]
     # The resource type for which access is granted
     resources: ["secrets"]
     # The permissions granted by the ClusterRole
     verbs: ["get", "watch", "list"]
   

2. 套用 ClusterRole 資訊清單：

   kubectl apply -f secret-viewer-cluster-role.yaml
   

3. 將下列 ClusterRoleBinding 資訊清單儲存為 secret-viewer-cluster-role-binding.yaml。繫結會將secret-viewer角色授予用戶端設定檔中定義的使用者名稱。

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name:  people-who-view-secrets
   subjects:
   - kind: User
     name: ISSUER_URI#USER
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     name: secret-viewer
     apiGroup: rbac.authorization.k8s.io
   

   更改下列內容：

   • ISSUER_URI：用戶端設定檔中 spec.authentication.oidc.issuerURI 的核發者 URI。
   • USER：權杖中的使用者 ID，位於用戶端設定檔 spec.authentication.oidc.userClaim 中設定的聲明名稱下方。

4. 套用 ClusterRoleBinding 資訊清單：

   kubectl apply -f secret-viewer-cluster-role-binding.yaml
   

登入及驗證叢集

開發人員可從管理員取得 OIDC 設定檔，並驗證叢集。

1. 下載管理員提供的 login-config.yaml 檔案。

2. 安裝 Google Cloud CLI SDK，其中提供獨立的 OIDC 元件。執行下列指令即可安裝：

   gcloud components install kubectl-oidc
   

3. 驗證叢集：

   kubectl oidc login --cluster=CLUSTER_NAME --login-config=login-config.yaml
   

   系統會開啟網頁瀏覽器，讓你完成驗證程序。

4. 完成驗證後，您就可以執行 kubectl 指令，例如：

   kubectl get pods
   

停用 GKE 適用的 Identity Service

您可以使用 gcloud CLI 停用 GKE 適用的 Identity Service。如要停用 GKE Identity Service，請執行下列指令：

gcloud container clusters update CLUSTER_NAME \
    --no-enable-identity-service

已知限制

gke-oidc-envoy 元件負責使用 GKE 適用的 Identity Service 向叢集進行驗證，且副本數量固定。也就是說，系統不會自動擴充資源來處理增加的流量。在地區叢集中，這個元件會部署三個副本。

您無法直接調度 gke-oidc-envoy Deployment。我們強烈建議您遷移至員工身分聯盟，取得可擴充且更穩固的解決方案。

後續步驟

• 進一步瞭解員工身分聯盟。
• 進一步瞭解如何部署工作負載。