以前のバージョンの GKE On-Prem のドキュメントを表示しています。最新のドキュメントをご覧ください

OpenID Connect(OIDC)による認証

このページでは、ユーザー クラスタへの認証に OpenID プロバイダを使用するよう GKE On-Prem を構成する方法について説明します。AD FS で OIDC を使用する方法については、OIDC と AD FS での認証を参照をご覧ください。

GKE On-Prem 認証フローの概要については、認証をご覧ください。

概要

GKE On-Prem は、ユーザー クラスタの Kubernetes API サーバーとやり取りする認証メカニズムの 1 つとして OpenID Connect(OIDC)をサポートしています。OIDC を使用すると、組織内の標準的な手順に従って Kubernetes クラスタへのアクセスを管理して、従業員のアカウントの作成、有効化、無効化を行うことが可能です。

従業員が OIDC 認証フローを使用するには、次の 2 つの方法があります。

  • 従業員は、kubectl を使用して、OIDC フローを開始できます。このフローを自動化するためには、GKE On-Prem で kubectl プラグインである OIDC 用 Kubectl プラグインを指定します。

  • 従業員は、Google Cloud Console を使用して、OIDC 認証フローを開始できます。

この演習では、kubectl と Cloud Console の両方のオプションを構成します。

始める前に

このトピックでは、OAuth 2.0OpenID Connect について理解していることを前提にしています。このトピックでは、OpenID のスコープクレームについて理解していることを前提としています。

OpenID プロバイダの選択

このセクションは管理者向けです。

任意の OpenID プロバイダを使用できます。認定プロバイダのリストについては、OpenID 認定をご覧ください。

1 つの方法として、Active Directory Federated Services(AD FS)を OpenID プロバイダとして使用し、Active Directory のオンプレミス インスタンスを従業員データベースとして使用します。詳細については、OIDC と AD FS による認証をご覧ください。

OIDC 用 Kubectl プラグインのダウンロード

このセクションは OIDC 用 Kubectl プラグインを使用する管理者と従業員を対象としています。

プラグインをダウンロードしてアクセス権限を設定します。

Linux

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/linux_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Windows

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/windows_amd64/kubectl-oidc .

macOS

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/darwin_amd64/kubectl-oidc .
chmod +x kubectl-oidc

プラグインのインストール

プラグインをインストールして、実行可能ファイルを PATH の任意の場所に移動します。実行可能ファイルの名前は kubectl-oidc とする必要があります。詳細は、kubectl プラグインのインストールをご覧ください。

OIDC 用 Kubectl プラグインのリダイレクト URL の作成

このセクションは管理者向けです。

OpenID プロバイダとの関係を確立するときは、プロバイダが ID トークンを OIDC の Kubectl Plugin に返すために使用できるリダイレクト URL を指定する必要があります。Kubectl Plugin for OIDC は、各従業員のローカルマシンで実行され、任意のポートでリッスンします。この目的に適した 1024 より大きいポート番号を選択します。リダイレクト URL は次のようになります。

http://localhost:[PORT]/callback

ここで、[PORT] はポート番号です。

OpenID プロバイダを構成するときに、リダイレクト URL の 1 つとして http://localhost:[PORT]/callback を指定します。その方法は、プロバイダによって異なります。

Cloud Console 用のリダイレクト URL の構成

このセクションは管理者向けです。

kubectl のリダイレクト URL に加えて、Cloud Console 用のリダイレクト URL が必要です。Cloud Console のリダイレクト URL は次のとおりです。

https://console.cloud.google.com/kubernetes/oidc

OIDC プロバイダを構成するときに、リダイレクト URL の 1 つとして、https://console.cloud.google.com/kubernetes/oidc を指定します。方法はプロバイダによって異なります。

OpenID プロバイダを使用したクライアント アプリケーションの登録

このセクションは管理者向けです。

従業員が OpenID プロバイダで Kubectl Plugin for OIDC または Cloud Console を使用するには、その 2 つのクライアントを OpenID プロバイダに登録する必要があります。登録には次の手順が含まれます。

  • プロバイダの発行者 URI を確認します。これは、OIDC または Cloud Console 用の Kubectl プラグインが認証リクエストを送信する場所です。

  • プロバイダに、OIDC 用 Kubectl プラグインのリダイレクト URL を指定します。

  • プロバイダに Cloud Console 用のリダイレクト URL を提供します。この URL は https://console.cloud.google.com/kubernetes/oidc です。

  • 単一のクライアント ID を設定します。 プロバイダが OIDC 用 と Cloud Console 用の両方の Kubectl プラグインを識別するために使用する ID です。

  • 単一のクライアント シークレットを設定します。OIDC と Cloud Console 用の Kubectl プラグインはどちらもこの Secret を OpenID プロバイダの認証に使用します。

  • OIDC または Cloud Console 用の Kubectl プラグインがユーザーのセキュリティ グループをリクエストするために使用するカスタム スコープを確立します。

  • プロバイダがユーザーのセキュリティ グループを返すために使用するカスタム クレーム名を設定します。

これらの手順は、OpenID プロバイダによって異なります。AD FS で登録手順を実行する方法については、OIDC と AD FS による認証をご覧ください。

GKE On-Prem 構成ファイルに oidc 仕様を入力する

このセクションは、OIDC 使用を前提に構成されたクラスタを作成する従業員を対象としています。

ユーザー クラスタを作成する前に、gkectl create-config を使用して GKE On-Prem 構成ファイルを生成します。構成には次の oidc 仕様が含まれます。プロバイダに固有の値で、oidc を入力します。

oidc:
  issuerurl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: 必須。OpenID プロバイダの URL で、https://example.com/adfs がその例です。OIDC と Cloud Console 用の Kubectl プラグインを例とするクライアント アプリケーションは、この URL に承認リクエストを送信します。Kubernetes API サーバーは、この URL を使用してトークン検証用の公開鍵を検出します。HTTPS を使用する必要があります。
  • clientid: 必須です。OpenID プロバイダへの認証リクエストを行うクライアント アプリケーションの ID。OIDC 用 と Cloud Console 用の両方の Kubectl プラグインでこの ID が使用されます。
  • clientsecret: 省略可。クライアント アプリケーション用の Secret。OIDC 用 と Cloud Console 用の両方の Kubectl プラグインでこの Secret が使用されます。
  • username: 省略可。ユーザー名として使用する JWT クレーム。デフォルトは sub で、これはエンドユーザーの一意の識別子である必要があります。OpenID プロバイダに応じて、emailname などの他のクレームを選択できます。ただし、他のプラグインとの競合を避けるため、email 以外のクレームには発行者の URL が先頭に付加されます。
  • usernameprefix: 省略可。既存の名前と競合しないように、ユーザー名のクレームの先頭に付加されるプレフィックス。このフィールドを指定せず、usernameemail 以外の値の場合、プレフィックスはデフォルトの issuerurl# になります。値 - を使用するとプレフィックスをすべて無効にします。
  • group: 省略可。プロバイダがセキュリティ グループを返すために使用する JWT クレーム。
  • groupprefix: 省略可。既存の名前と競合しないように、グループ クレームの先頭に付加されるプレフィックス。たとえば、グループ foobar と接頭辞 gid- が指定されている場合、gid-foobar となります。
  • scopes: 省略可。OpenID プロバイダにカンマ区切りのリストとして送信する追加のスコープ。
  • extraparams: 省略可。OpenID プロバイダにカンマ区切りリストとして送信する追加の Key-Value パラメータ。
  • usehttpproxy: 省略可。ユーザー認証用のオンプレミス OIDC プロバイダへの Connect Agent でのアクセスを許可するため、クラスタにリバース プロキシをデプロイするかどうかを指定します。値は文字列("true" または "false")で指定してください。
  • capath: 省略可。ID プロバイダのウェブ証明書を発行した認証局(CA)の証明書へのパス。この値は必須ではありません。たとえば、ID プロバイダの証明書が周知されている公開 CA によって発行された場合は、ここに値を指定する必要はありません。

例: ユーザーとグループの承認

多くのプロバイダは、ユーザー識別プロパティ(メールやユーザー ID など)をトークンにエンコードします。ただし、これらのプロパティには認証ポリシーに関する潜在的なリスクがあります。

  • ユーザー ID を使用すると、ポリシーの読み取りと監査が難しくなります。
  • メールでは、可用性リスク(ユーザーがメインのメールを変更した場合)とセキュリティ リスク(メールを再割り当てできる場合)の両方が発生する可能性があります。

そのため、グループ ポリシーを使用することをおすすめします。グループ ID は永続的で監査が容易なためです。

プロバイダが次のフィールドを含む ID トークンを作成したとします。

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList: ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}
このトークン形式では、構成ファイルの oidc 仕様を次のように指定します。
issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

ユーザー クラスタを作成すると、Kubernetes の役割ベースのアクセス制御(RBAC)を使用して、認証済みユーザーに特権アクセスを付与できます。たとえば、クラスタの Secret への読み取り専用アクセス権を付与する ClusterRole を作成し、認証されたグループに役割をバインドする ClusterRoleBinding リソースを作成できます。

ClusterRole

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

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-admins
subjects:
  # Allows anyone in the "us-east1-cluster-admins" group to
  # read Secrets in any namespace within this cluster.
- kind: Group
  name: gid-us-east1-cluster-admins # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
  # Allows this specific user to read Secrets in any
  # namespace within this cluster
- kind: User
  name: uid-u98523-4509823
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Kubernetes API サーバーの CA 証明書の保存

このセクションは、ユーザー クラスタを作成し、OIDC 用の Kubectl プラグインを使用する従業員を対象としています。

ユーザー クラスタは Kubernetes API サーバーを備えています。また、ユーザー クラスタの kubeconfig ファイルには、Kubernetes API サーバーに証明書を発行した CA の証明書が保存されています。CA の証明書は、base-64 でエンコードされた certificate-authority-data フィールドの値です。この値をデコードして server-ca-cert のようなローカル ファイルに保存する必要があります。

cat [USER_CLUSTER_KUBECONFIG]  | grep certificate-authority-data | awk '{ print $2}' | base64 --decode > server-ca-cert

クライアント認証構成ファイルの生成

このセクションは、ユーザー クラスタを作成し、OIDC 用の Kubectl プラグインを使用する従業員を対象としています。

クライアント認証構成ファイルを生成するには、次のコマンドを入力します。

Linux

kubectl oidc client-config \
--issuer-uri [ISSUER_URI] \
--redirect-uri [REDIRECT_URL] \
--client-id [CLIENT_ID] \
--client-secret [CLIENT_SECRET] \
--scopes "[CUSTOM_SCOPES]" \
--cluster-name [USER_CLUSTER_NAME] \
--server [CLUSTER_URL] \
--server-ca-file [SERVER_CA_CERT] \
--issuer-ca-file [PROVIDER_CA_CERT] \
--extra-params [KEY]=[VALUE], ... # e.g. --extra-params "resource=token-groups-claim"
> client-config.yaml

ここで

  • [ISSUER_URI]は発行者の URI です。
  • [REDIRECT_URL] は OIDC 用 Kubectl プラグインのリダイレクト URL です。
  • [CLIENT_ID] は OIDC 用の Kubectl プラグインのクライアント ID です。
  • [CLIENT_SECRET] は OIDC 用の Kubectl Plugin のクライアント シークレットです。
  • [USER_CLUSTER_NAME]はユーザークラスタの名前です。
  • [CLUSTER_URL] は、ユーザー クラスタの Kubernetes API サーバーの URL です。
  • [SERVER_CA_FILE] は、Kubernetes API サーバーに証明書を発行した CA の証明書へのパスです。これは、前のセクションで作成した証明書ファイルです。
  • [PROVIDER_CA_CERT]は、OpenID プロバイダの証明書に署名した CA の証明書へのパスです。これは、クラスタ構成ファイルの oidc:cacert の値と同じです。
  • [CUSTOM_SCOPES]は、セキュリティグループのカスタムスコープのカンマ区切りリストです。これは、クラスタ構成ファイルの oidc:scopes の値と同じです。
  • --extra-params [KEY]=[VALUE], ... は、OpenID プロバイダへの承認リクエストに含めるカンマ区切りの Key-Value ペアのリストです。

PowerShell

kubectl oidc client-config `
--issuer-uri [ISSUER_URI] `
--redirect-uri [REDIRECT_URL] `
--client-id [CLIENT_ID] `
--client-secret [CLIENT_SECRET] `
--scopes "[CUSTOM_SCOPES]" `
--cluster-name [USER_CLUSTER_NAME] `
--server [CLUSTER_URL] `
--server-ca-file [SERVER_CA_CERT] `
--issuer-ca-file [PROVIDER_CA_CERT] `
--extra-params [KEY]=[VALUE]
> client-config.yaml

ここで

  • [ISSUER_URI]は発行者の URI です。
  • [REDIRECT_URL]は、OIDC 用の Kubectl プラグインのリダイレクト URL です。
  • [CLIENT_ID] は OIDC 用の Kubectl プラグインのクライアント ID です。
  • [CLIENT_SECRET]は、OIDC の Kubectl プラグインのクライアントシークレットです。
  • [USER_CLUSTER_NAME]はユーザークラスタの名前です。
  • [CLUSTER_URL]は、ユーザークラスタの Kubernetes API サーバーの URL です。
  • [SERVER_CA_FILE] は、Kubernetes API サーバーに証明書を発行した CA の証明書へのパスです。これは、前のセクションで作成した証明書ファイルです。
  • [PROVIDER_CA_CERT] は、OpenID プロバイダの証明書に署名した CA の証明書へのパスです。これは、クラスタ構成ファイルの oidc:cacert の値と同じです。
  • [CUSTOM_SCOPES] は、セキュリティ グループのカスタム スコープのカンマ区切りのリストです。これは、クラスタ構成ファイルの oidc:scopes の値と同じです。
  • --extra-params [KEY]=[VALUE], ... は、OpenID プロバイダへの承認リクエストに含めるカンマ区切りの Key-Value ペアのリストです。

このコマンドは、client-config.yaml というクライアント認証構成ファイルを生成します。このファイルは手動で編集しないでください。

OIDC 用の Kubectl プラグインを使用したユーザー クラスタに対する認証

このセクションは、ユーザー クラスタを作成し、OIDC 用の Kubectl プラグインを使用する従業員を対象としています。

  1. client-config.yaml ファイルを使用してプラグインを初期化します。

    kubectl oidc login --clientconfig-file=client-config.yaml --user [NAME] \
        --kubeconfig [KUBECONFIG_OUTPUT_PATH]

    ここで

    • [NAME] は、ユーザー名です。
    • [KUBECONFIG_OUTPUT_PATH]は、Kubectl Plugin for OIDC が認証情報を保存する kubeconfig ファイルへのパスです。

    kubectl oidc login で、認証情報を入力できるブラウザを起動します。

    現在指定されている kubeconfig ファイルには、kubectl でユーザー クラスタ上の Kubernetes API サーバーに認証するために使用される ID トークンが含まれています。

    注: Windows ユーザーは、kubectl oidc login ではなく kubectl-oidc.exe login としてコマンドを実行する必要があります。

  2. 認証が成功したことを確認するには、kubectlコマンドを実行します。例:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Google Cloud Console での OIDC の使用

このセクションは、ユーザー クラスタを作成し、Google Cloud Console を使用してクラスタに対して認証を行う従業員を対象としています。

  1. クラスタが OIDC 用に構成されていることを確認します。

  2. クラスタが、自動でクラスタ作成中に、または手動で Google Cloud で登録されていることを確認します。

  3. Cloud Console の [Kubernetes クラスタ] ページにアクセスします。

    [Kubernetes クラスタ] ページにアクセス

  4. クラスタのリストで、GKE On-Prem クラスタを見つけ、[Login] をクリックします。

  5. [クラスタ用に構成された ID プロバイダを使用して認証する] を選択し、[ログイン] をクリックします。

    ID プロバイダにリダイレクトされ、アカウントにアクセスしている Cloud Console へのログインや同意が必要となる場合があります。その後、Cloud Console の [Kubernetes クラスタ] ページに再度リダイレクトされます。

GKE On-Prem の OIDC のトラブルシューティング

無効な構成

Cloud Console でクラスタから OIDC 構成を読み取れない場合、[ログイン] ボタンは無効になります。

無効なプロバイダ構成

ID プロバイダの構成が無効な場合は、[ログイン] をクリックした後に、ID プロバイダからのエラー画面が表示されます。プロバイダ固有の手順に従って、プロバイダまたはクラスタを正しく構成します。

無効な権限

認証フローを完了してもクラスタの詳細が表示されない場合は、OIDC で使用したアカウントに適切な RBAC 権限が付与されていることを確認してください。これは、Cloud Console へのアクセスに使用するアカウントとは異なる場合があることに注意してください。

Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct

このエラーは、承認サーバーから同意を求められたものの、必要な認証パラメータが指定されていない場合に発生します。prompt=consent パラメータを GKE On-Prem 構成ファイルの oidc: extraparams フィールドに指定し、--extra-params prompt=consent フラグを使用してクライアント認証ファイルを再生成します。