外部 ID プロバイダを使用して GKE に対する認証を行う

このドキュメントでは、Google Kubernetes Engine（GKE）クラスタに対して認証を行うように外部 ID プロバイダを構成する方法について説明します。

概要

GKE 用 Identity Service は、既存の ID ソリューションを GKE クラスタに拡張します。OpenID Connect（OIDC）のサポートにより、組織内のユーザー アカウントの作成、有効化、無効化の標準的な手順で Kubernetes クラスタへのアクセスを管理できます。GKE 用 Identity Service は OIDC ID プロバイダに限定されています。

始める前に

  • このドキュメントを読む前に、次の認証と OpenID のコンセプトを理解しておいてください。

  • ヘッドレス システムはサポートされていません。ブラウザベースの認証フローが使用されて、プロンプトで同意が求められ、ユーザー アカウントを承認します。

作業を始める前に、次のことを確認してください。

  • Google Kubernetes Engine API を有効にする。
    • Google Kubernetes Engine API の有効化
  • このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。

GKE 向け Identity Service を使用するユーザー

このドキュメントのタスクは、次のいずれかに該当する方を対象としています。

  • クラスタ管理者: 1 つ以上のユーザー クラスタを作成し、そのクラスタを使用するデベロッパー向けの認証構成ファイルを作成します。

  • デベロッパー: 1 つ以上のクラスタでワークロードを実行し、OIDC を使用して認証します。

仕組み

GKE クラスタで GKE 用 Identity Service を設定して使用するには、クラスタ管理者が次の手順を行います。

  1. クラスタで GKE 用 Identity Service を有効にする。
  2. GKE 用 Identity Service を構成する。
  3. クラスタの RBAC ポリシーを作成する。

クラスタ管理者が GKE 用 Identity Service を構成すると、デベロッパーはクラスタにログインして認証できるようになります。

クラスタで GKE 用 Identity Service を有効にする

このセクションは、クラスタ管理者を対象としています。

デフォルトでは、Identity and Access Management（IAM）がクラスタ認証の ID プロバイダとして構成されます。サードパーティの ID プロバイダで OIDC を使用する場合は、Google Cloud CLI を使用して新規または既存のクラスタで GKE 用 Identity Service を有効にできます。

新しいクラスタで GKE 用 Identity Service を有効にする

GKE 用 Identity Service が有効になったクラスタを作成するには、次のコマンドを実行します。

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 によって作成された Kubernetes オブジェクト

次の表は、クラスタで GKE 用 Identity Service を有効にするときに作成される Kubernetes オブジェクトを示したものです。

Kubernetes オブジェクト
anthos-identity-service Namespace
GKE 用 Identity Service のデプロイに使用されます。
kube-public Namespace
defaultクライアント構成ファイルに使用されます。
gke-oidc-envoy LoadBalancer
OIDC リクエストのエンドポイント。デフォルトで外部。限定公開クラスタまたは厳格なネットワーク ポリシーが適用されたクラスタで作成されている場合、エンドポイントはクラスタ Virtual Private Cloud の内部にあります。
anthos-identity-service Namespace に作成されます。
gke-oidc-service ClusterIP
gke-oidc-envoy Deployment と gke-oidc-service Deployment との間の通信を容易にします。
anthos-identity-service Namespace に作成されます。
gke-oidc-envoy Deployment
gke-oidc-envoy LoadBalancer に公開されたプロキシを実行します。gke-oidc-service と通信して ID トークンを検証します。Kubernetes API サーバーのプロキシとして機能し、API サーバーにリクエストを渡すときにユーザーになりすまします。
anthos-identity-service Namespace に作成されます。
gke-oidc-service Deployment
ID トークンを検証し、ClientConfig リソース用の Validating Admission Webhook を提供します。
anthos-identity-service Namespace に作成されます。
gke-oidc-operator Deployment
クライアント構成と gke-oidc-envoy LoadBalancer を調整します。
anthos-identity-service Namespace に作成されます。
gke-oidc-certs Secret
LoadBalancer 用のクラスタ認証局（CA）と TLS 証明書が含まれています。
anthos-identity-service Namespace に作成されます。
default ClientConfig CRD
推奨認証方法、ID プロバイダの構成、ユーザーとグループのクレームのマッピングなどの OIDC パラメータが含まれます。ID トークンの検証に使用されます。クラスタ管理者が使用し、OIDC 設定を構成してからデベロッパーに配布します。
kube-public Namespace に作成されます。

GKE 用 Identity Service を構成する

このセクションは、クラスタ管理者を対象としています。

default ClientConfig をダウンロードして変更することで、GKE 用 Identity Service を構成できます。

  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 プロバイダに送信する追加の Key-Value パラメータ。
      • グループを承認するには、resource=token-groups-claim を使用します。
      • Microsoft Azure と Okta を認証するには、prompt=consent を使用します。
      • Cloud Identity の場合は、prompt=consent,access_type=offline を使用します。
    • ISSUER_URI: OIDC 認可リクエストを送信する URL（たとえば、https://example.com/adfs）。Kubernetes API サーバーは、この URL を使用してトークン検証用の公開鍵を検出します。URI には HTTPS を使用する必要があります。Cloud Identity の場合は、https://accounts.google.com を使用します。
    • KUBECTL_REDIRECT_URL: kubectl oidc login が認証に使用するリダイレクト URL。通常は、http://localhost:PORT/callback という形式です。ここで、PORT はデベロッパー ワークステーションで使用可能な 1024 を超えるポートです（例: http://localhost:10000/callback）。この URL は、クライアント アプリケーションの承認済みのリダイレクト URL として OIDC プロバイダに登録する必要があります。Google Identity を OIDC プロバイダとして使用する場合は、リダイレクト URI を設定するで手順をご覧ください。
    • SCOPES: OIDC プロバイダに送信する追加のスコープ。
      • Microsoft Azure と Okta には offline_access スコープが必要です。
      • Cloud Identity の場合は、openid, email を使用して、email クレーム内のメールアドレスを含む ID トークンを取得します。
    • USER: ID トークンのユーザー クレーム。
    • GROUPS: ID トークンのグループ クレーム。
    • USER_PREFIX: 既存の名前と競合しないように、ユーザー クレームの先頭に付加される接頭辞。デフォルトでは、発行元の接頭辞が Kubernetes API サーバーに渡された userID に追加されます（ユーザー クレームが email の場合を除く）。生成されるユーザー ID は ISSUER_URI#USER です。接頭辞を使用することをおすすめしますが、USER_PREFIX を - に設定すると接頭辞を無効にできます。
    • GROUP_PREFIX: 既存の名前と競合しないように、グループ クレームの先頭に付加される接頭辞。たとえば、foobar という名前の 2 つのグループがある場合、接頭辞 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 Service を構成する

限定公開クラスタなど、厳格なネットワーク ポリシーが設定されているクラスタで想定どおりに動作するように GKE 用 Identity Service を構成するには、次の手順を行います。

  1. TCP ポート 15000 のファイアウォール ルールを追加して、コントロール プレーンが ClientConfig 検証 Webhook と通信できるようにします。
  2. gke-oidc-envoy が内部ロードバランサとして作成されている場合は、VPC に公開します。
  3. クラスタ内のトラフィックを拒否するポリシーが存在する場合は、TCP ポート 8443 にファイアウォール ルールを追加して、gke-oidc-envoy Deployment が gke-oidc-service Deployment と通信できるようにします。

Identity Service for GKE コンポーネント バージョン 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 Service を構成すると、静的 IP アドレスなどのカスタム アノテーションとプロパティを gke-oidc-envoy ロードバランサに追加できます。gke-oidc-envoy Service を編集するには、次のコマンドを実行します。

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

GKE の TCP/UDP ロード バランシングを構成する方法をドキュメントで確認する。

クラスタの RBAC ポリシーを作成する

このセクションは、クラスタ管理者を対象としています。

管理者は Kubernetes ロールベース アクセス制御（RBAC）を使用して、認証済みクラスタ ユーザーにアクセスを許可します。クラスタに RBAC を構成するには、各デベロッパーに RBAC ロールを付与する必要があります。特定の Namespace のリソースへのアクセスを許可するには、Role と RoleBinding を作成します。クラスタ全体のリソースへのアクセスを許可するには、ClusterRole と ClusterRoleBinding を作成します。

たとえば、クラスタ全体のすべての Secret オブジェクトを表示する必要があるユーザーを考えてみましょう。次の手順では、必要な RBAC ロールをこのユーザーに付与します。

  1. 次の ClusterRole マニフェストを secret-viewer-cluster-role.yaml として保存します。このロールを付与されたユーザーは、クラスタ内の Secret に対して get、watch、list オペレーションを行えます。

    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: クライアント構成ファイルの spec.authentication.oidc.userClaim で構成されたクレーム名の下のトークンのユーザー ID。

  4. ClusterRoleBinding マニフェストを適用します。

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

クラスタにログインして認証する

このセクションはデベロッパーを対象としています。

管理者から OIDC 構成ファイルを受け取ったら、クラスタに対する認証が行えます。

  1. 管理者から提供された login-config.yaml ファイルをダウンロードします。

  2. 個別の OIDC コンポーネントを提供する Google Cloud CLI SDK をインストールします。これをインストールするには、次のコマンドを実行します。

    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

次のステップ