OIDC で GKE Identity Service のクラスタを設定する

このドキュメントは、個々のクラスタで GKE Identity Service を設定し、デベロッパーと他のユーザーが OpenID Connect（OIDC）プロバイダから既存の ID の詳細を使用してクラスタにログインできるようにすることを必要とするクラスタ管理者またはアプリケーションオペレーターを対象としています。

前提条件

クラスタは、オンプレミス（VMware またはベアメタル）、AWS、または Azure 上の GKE クラスタである必要があります。クラスタごとの OIDC 構成は、接続されたクラスタまたは GKE クラスタではサポートされていません。
Google Cloud コンソールで認証するには、OIDC 認証用に構成する各クラスタをプロジェクトフリートに登録する必要があります。

始める前に

設定を開始する前に、プロバイダに GKE Identity Service を登録するに記載されている必須情報（GKE Identity Service のクライアント ID やシークレットなど）がプラットフォーム管理者から提供されていることを確認します。
次のコマンドラインツールがインストールされていることを確認します。
- Google Cloud CLI の最新バージョン。Google Cloud とやり取りするためのコマンドラインツールである gcloud が含まれています。Google Cloud CLI をインストールする必要がある場合は、インストールガイドをご覧ください。
- kubectl。Kubernetes クラスタにコマンドを実行するために使用します。kubectl をインストールする必要がある場合は、こちらの説明に従ってインストールしてください。
Google Cloud を操作するシェル環境として Cloud Shell を使用する場合は、これらのツールがインストールされます。
クラスタが登録されているプロジェクトで使用するために、gcloud CLI が初期化されていることを確認します。
現在の VPC の外部にある AWS または Azure GKE クラスタのコントロールプレーンを踏み台インスタンス経由で接続する必要がある場合は、この設定を行う前に踏み台インスタンスを作成し、ポート 8118 で SSH トンネルを開始してください。次に、このガイドに従って HTTPS_PROXY=http://localhost:8118 を使用する際に、kubectl コマンドを先頭に付けます。SSH トンネルの開始時に別のポートを使用した場合は、8118 を選択したポートに置き換えます。

クラスタを構成する

選択したプロバイダを使用するようにクラスタを構成するには、ID プロバイダの詳細、ユーザー ID として ID プロバイダが提供する JWT トークンの情報、クライアントアプリケーションとして GKE Identity Service を登録する際に提供されたその他の情報を指定する必要があります。

たとえば、プロバイダが次のフィールドを含む ID トークンを作成するとします。ここで、iss は ID プロバイダの URI、sub はユーザー、groupList はユーザーが属するセキュリティグループのリストです。

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

ユーザー側の構成には、次のように対応するフィールドが含まれている必要があります。

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

構成の作成に必要な情報のほとんどは、プラットフォーム管理者または組織の ID 管理者から提供されます。

GKE Identity Service は、ClientConfig という Kubernetes カスタムリソースタイプ（CRD）を使用してクラスタを構成します。ClientConfig には、GKE Identity Service が ID プロバイダとやり取りするために必要なすべての情報のフィールドが含まれています。各 GKE クラスタには、以下の手順に沿って構成の詳細で更新する kube-public Namespace に default という ClientConfig リソースがあります。

広く使用されているプロバイダ用の具体的な構成例については、プロバイダ固有の構成をご覧ください。

kubectl

デフォルトの 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_STRING
      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.
...

次の表に、ClientConfig oidc オブジェクトのフィールドを示します。ほとんどのフィールドは省略できます。追加する必要があるフィールドは、ID プロバイダと、GKE Identity Service のプロバイダを構成する際にプラットフォーム管理者が選択した設定オプションによって変わります。

フィールド	必須	説明	形式
name	○	この構成を識別するために使用する名前で、通常は ID プロバイダ名です。構成名の先頭は英字で、それに続く最大 39 文字の英小文字、数字、ハイフンで構成します。末尾をハイフンにすることはできません。	文字列
certificateAuthorityData	×	プラットフォーム管理者が指定した場合は、ID プロバイダ用の PEM エンコードの証明書の文字列。`certificateAuthorityData` では、結果の文字列が 1 行に含まれます。	文字列
clientID	○	OIDC プロバイダに GKE Identity Service を登録するときに返されたクライアント ID。	文字列
clientSecret	×	OIDC クライアントアプリケーションと OIDC プロバイダ間の共有シークレット。	文字列
deployCloudConsoleProxy	×	Google Cloud コンソールから一般公開されていないオンプレミスの ID プロバイダにインターネット経由で接続できるようにするプロキシがデプロイされているかどうかを表します。デフォルトの設定値は `false` です。	ブール値
extraParams	×	ID プロバイダに送信する追加の Key=Value パラメータ。カンマ区切りのリストとして指定します。例: prompt=consent,access_type=offline。	カンマ区切りのリスト
groupsClaim	×	JWT クレーム（フィールド名）。プロバイダがアカウントのセキュリティグループを返すために使用します。	文字列
groupPrefix	×	複数の ID プロバイダの構成がある場合に、アクセス制御ルールの既存の名前と競合しないように、セキュリティグループ名に追加する接頭辞（通常はプロバイダ名）。	文字列
issuerURI	○	ID プロバイダに対して認可リクエストを行う URI。URI には HTTPS を使用し、末尾にスラッシュを付けないでください。	URL 文字列
kubectlRedirectURI	○	gcloud CLI で使用され、プラットフォーム管理者が登録時に指定したリダイレクト URL とポート（通常は `http://localhost:PORT/callback` の形式）。	URL 文字列
scopes	○	OpenID プロバイダに送信する追加のスコープ。たとえば、Microsoft Azure と Okta では、`offline_access` スコープが必要です。	カンマ区切りのリスト
userClaim	×	プロバイダがユーザーアカウントの識別に使用する JWT クレーム（フィールド名）。ここに値が指定されていないと、GKE Identity Service は「sub」を使用します。これは多くのプロバイダで使用されるユーザー ID クレームです。OpenID プロバイダによっては、email や name などのクレームを選択することもできます。名前が競合しないように、email 以外のクレームには、発行元の URL が先頭に付加されます。	文字列
userPrefix	×	デフォルトの接頭辞を使用しない場合にユーザークレームの先頭に付加する接頭辞。これにより、既存の名前と競合しないようにします。	文字列
enableAccessToken	×	有効になっている場合、GKE Identity Service は、ユーザーがコマンドラインからログインしたときに、ID プロバイダの userinfo エンドポイントを使用してグループ情報を取得できます。グループクレームを提供するプロバイダ（Okta など）がある場合は、このエンドポイントからセキュリティグループを使用して認可を行うことができます。未設定の場合、これは `false` とみなされます。	ブール値
プロキシ	×	ID プロバイダへの接続に使用するプロキシサーバーのアドレス（該当する場合）。たとえば、クラスタがプライベートネットワークにあり、パブリック ID プロバイダに接続する必要がある場合に設定する必要があります。例: `http://user:password@10.10.10.10:8888`。	文字列

ClientConfig が完成したら、ファイルを保存します。これにより、クラスタの ClientConfig が更新されます。構文エラーがある場合は、構成ファイルを再編集して修正するように求められます。

プロバイダ固有の構成

このセクションでは、一般的な OIDC プロバイダの構成ガイダンスについて説明します。これには独自の詳細をコピーして編集できる構成例も含まれます。

Azure AD

これは、Azure AD で GKE Identity Service を設定するためのデフォルトの構成です。この構成を使用すると、GKE Identity Service で Azure AD からユーザーとグループメンバーシップの情報を取得できます。また、グループに基づいて Kubernetes のロールベースアクセス制御（RBAC）を設定できます。ただし、この構成を使用すると、ユーザーごとに取得できるグループに約 200 個の上限が設定されます。

ユーザーあたり 200 個を超えるグループを取得する必要がある場合は、Azure AD（上級）の手順をご覧ください。

...
spec:
  authentication:
  - name: oidc-azuread
    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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

次のように置き換えます。

CLIENT_ID: プロバイダに GKE Identity サービスを登録するときに返されたクライアント ID。
CLIENT_SECRET: OIDC クライアントアプリケーションと OIDC プロバイダ間の共有シークレット。
TENANT: 認証する Azure AD アカウントの種類。サポートされている値は、テナント ID または特定のテナントに属するアカウントのテナント名です。テナント名はプライマリドメインとしても知られています。これらの値を確認する詳しい方法については、Microsoft Azure AD テナント ID とプライマリドメイン名を確認するをご覧ください。
PORT: gcloud CLI で使用されるリダイレクト URL 用に選択されたポート番号。登録時にプラットフォーム管理者が指定しています。

Azure AD（上級）

Azure AD のこのオプション構成では、ユーザーあたりのグループ数に制限はありません。GKE Identity Service で Microsoft Graph API を使用して、ユーザーとグループの情報を取得できます。

この構成をサポートするプラットフォームについては、Azure AD の高度な設定に関するページをご覧ください。

ユーザーあたり 200 個未満のグループを取得する必要がある場合は、ClientConfig の oidc アンカーを使用してデフォルト構成を使用することをおすすめします。詳細については、Azure AD の手順をご覧ください。

構成例の以下のフィールドはすべて必須です。

...
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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

次のように置き換えます。

NAME: この構成を識別するために使用する名前で、通常は ID プロバイダ名。構成名の先頭は英字で、それに続く最大 39 文字の英小文字、数字、ハイフンで構成します。末尾をハイフンにすることはできません。
PROXY_URL: ID プロバイダへの接続に使用するプロキシサーバーのアドレス（該当する場合）。たとえば、クラスタがプライベートネットワークにあり、パブリック ID プロバイダに接続する必要がある場合に設定する必要があります。例: http://user:password@10.10.10.10:8888。
CLIENT_ID: プロバイダに GKE Identity サービスを登録するときに返されたクライアント ID。
CLIENT_SECRET: OIDC クライアントアプリケーションと OIDC プロバイダ間の共有シークレット。
TENANT: 認証する Azure AD アカウントの種類。サポートされている値は、テナント ID または特定のテナントに属するアカウントのテナント名です。テナント名はプライマリドメインとしても知られています。これらの値を確認する詳しい方法については、Microsoft Azure AD テナント ID とプライマリドメイン名を確認するをご覧ください。
PORT: gcloud CLI で使用されるリダイレクト URL 用に選択されたポート番号。登録時にプラットフォーム管理者が指定しています。
GROUP_FORMAT: グループ情報を取得する形式。このフィールドには、ユーザーグループの ID または NAME に対応する値を指定できます。この設定は現在、ベアメタル Google Distributed Cloud デプロイのクラスタでのみ使用できます。
USER_CLAIM（省略可）: プロバイダがアカウントの識別に使用する JWT クレーム（フィールド名）。ここに値が指定されていないと、GKE Identity Service は email、preferred_username、sub の順番で値を使用して、ユーザーの詳細情報を取得します。この属性は、GKE Enterprise バージョン 1.28 以降で使用できます。

Okta

以下では、Okta を ID プロバイダとし、ユーザーとグループの両方を使用して認証を設定する手順について説明します。この構成により、Anthos Identity Service は、アクセストークンと Okta の userinfo エンドポイントを使用して、ユーザーとグループのクレームを取得します。

...
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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

グループアクセスの上限

Okta ユーザーの場合、Anthos Identity Service は、連結時のグループ名が 170,000 文字未満のユーザーのグループ情報を取得できます。これは、Okta の最大グループ長が与えられた約 650 グループのメンバーシップに相当します。ユーザーが所属するグループが多すぎる場合、認証の呼び出しは失敗します。

次のステップ

構成が適用されたら、クラスタにユーザーアクセスを設定するに進みます。