OIDC 認証用にフリートメンバークラスタを設定する

このドキュメントでは、クラスタ管理者またはアプリケーションオペレーターが、サードパーティの OpenID Connect（OIDC）プロバイダを使用した認証をサポートするようにクラスタを構成する方法について説明します。

制限事項

OIDC をサポートするクラスタタイプを使用する必要があります。

始める前に

Install the Google Cloud CLI.
外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。
gcloud CLI を初期化するには、次のコマンドを実行します。
```
gcloud init
```
gcloud CLI を初期化した後に更新して、必要なコンポーネントをインストールします。
```
gcloud components update
gcloud components install kubectl
```
必要なすべてのプロバイダ情報がプラットフォーム管理者から提供されていることを確認します。詳細については、ID プロバイダの詳細を共有するをご覧ください。
Google Cloud コンソールを使用して認証するには、構成する各クラスタをプロジェクトフリートに登録します。詳細については、フリート作成の概要をご覧ください。
現在の VPC ネットワークの外部にある AWS または Azure クラスタのコントロールプレーンを踏み台インスタンス経由で接続するには、踏み台インスタンスを作成し、ポート 8118 で SSH トンネルを開始してください。このドキュメントで kubectl コマンドを実行する場合は、コマンドの先頭に HTTPS_PROXY=http://localhost:PORT を追加します。ここで、PORT は SSH トンネルの開始時に使用したポート番号です。
Google Cloudの GKE クラスタの場合は、クラスタをフリートに登録します。

クラスタの構成

OIDC を使用してクラスタへの認証を構成するには、ClientConfig という名前の Kubernetes カスタムリソースに次の情報を追加します。

クライアント ID やシークレットなどの ID プロバイダに関する情報。
ID プロバイダが認証に使用する JSON ウェブトークン（JWT）に関する情報。
ID プロバイダに固有の追加のスコープまたはパラメータ。

プラットフォーム管理者または組織の ID 管理者から提供される必要がある情報の詳細については、ID プロバイダの詳細を共有するをご覧ください。

クラスタは、ClientConfig カスタムリソースのフィールドを使用して ID プロバイダとやり取りします。すべてのクラスタには、kube-public Namespace に default という名前の ClientConfig があります。変更する特定のフィールドは、ID プロバイダによって異なります。

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 は ID プロバイダの 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 の ID プロバイダ構成を複数追加できます。クラスタは、定義された順序で各構成による認証を試行し、認証が最初に成功した時点で停止します。次の ClientConfig の例では、特定の順序で複数の ID プロバイダを定義しています。

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 オブジェクトのフィールドを示します。追加する必要があるフィールドは、ID プロバイダトークンと、プラットフォーム管理者がプロバイダを構成した方法によって異なります。

フィールド	必須	説明	形式
name	○	この構成を識別するために使用する名前で、通常は ID プロバイダ名です。構成名の先頭は英字で、それに続く最大 39 文字の英小文字、数字、ハイフンで構成します。末尾をハイフンにすることはできません。	文字列
certificateAuthorityData	いいえ	プラットフォーム管理者が指定した場合は、ID プロバイダ用の PEM エンコードの証明書の文字列。`certificateAuthorityData` では、結果の文字列が 1 行に含まれます。	文字列
clientID	○	ID プロバイダのクライアント 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 クレーム（フィールド名）。ここに値を指定しない場合、デフォルト値は「sub」になります。これは多くのプロバイダで使用されるユーザー ID クレームです。OpenID プロバイダによっては、email や name などのクレームを選択することもできます。名前が競合しないように、email 以外のクレームには、発行元の URL が先頭に付加されます。	文字列
userPrefix	いいえ	デフォルトの接頭辞を使用しない場合にユーザークレームの先頭に付加する接頭辞。これにより、既存の名前と競合しないようにします。	文字列
enableAccessToken	いいえ	有効になっている場合、クラスタは、ユーザーがコマンドラインからログインしたときに、ID プロバイダの userinfo エンドポイントを使用してグループ情報を取得できます。グループクレームを提供するプロバイダ（Okta など）がある場合は、このエンドポイントからセキュリティグループを使用して認可を行うことができます。未設定の場合、これは `false` とみなされます。	ブール値
プロキシ	いいえ	ID プロバイダへの接続に使用するプロキシサーバーのアドレス（該当する場合）。たとえば、クラスタがプライベートネットワークにあり、パブリック ID プロバイダに接続する必要がある場合に設定する必要があります。例: `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 で使用されるリダイレクト URL 用に選択されたポート番号。登録時にプラットフォーム管理者が指定しています。

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: この構成を識別するために使用する名前で、通常は ID プロバイダ名。構成名の先頭は英字で、それに続く最大 39 文字の英小文字、数字、ハイフンで構成します。末尾をハイフンにすることはできません。
PROXY_URL: ID プロバイダへの接続に使用するプロキシサーバーのアドレス（該当する場合）。たとえば、クラスタがプライベートネットワークにあり、パブリック ID プロバイダに接続する必要がある場合に設定する必要があります。例: 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 で使用されるリダイレクト URL 用に選択されたポート番号。登録時にプラットフォーム管理者が指定しています。
GROUP_FORMAT: グループ情報を取得する形式。このフィールドには、ユーザーグループの ID または NAME に対応する値を指定できます。この設定は、ベアメタル Google Distributed Cloud デプロイのクラスタでのみ使用できます。
USER_CLAIM（省略可）: プロバイダがアカウントの識別に使用する JWT クレーム（フィールド名）。ここに値が指定されていない場合、クラスタは、email、preferred_username、sub の値を順に使用してユーザーの詳細情報を取得します。この属性は、バージョン 1.28 以降で使用できます。

Okta

以下では、Okta を ID プロバイダとし、ユーザーとグループの両方を使用して認証を設定する手順について説明します。この構成により、クラスタはアクセストークンと 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 ユーザーの場合、クラスタは、連結時のグループ名が 170,000 文字未満のユーザーのグループ情報を取得できます。これは、Okta の最大グループ長が与えられた約 650 グループのメンバーシップに相当します。ユーザーが所属するグループが多すぎる場合、認証の呼び出しは失敗します。

次のステップ

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