このページでは、ユーザー クラスタへの認証に 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
と Google Cloud コンソールの両方のオプションを構成します。
準備
このトピックでは、OAuth 2.0 と OpenID 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 プロバイダとの関係を確立する際に、プロバイダが OIDC 用 Kubectl プラグインに ID トークンを返すために使用できるリダイレクト URL を指定する必要があります。OIDC 用の Kubectl プラグインは、各従業員のローカルマシンで実行され、任意のポートでリッスンします。この目的に適した 1024 より大きいポート番号を選択します。リダイレクト URL は次のようになります。
http://localhost:[PORT]/callback
ここで、[PORT] はポート番号です。
OpenID プロバイダを構成するときに、リダイレクト URL の 1 つとして、http://localhost:[PORT]/callback を指定します。方法はプロバイダによって異なります。
Google Cloud コンソール用のリダイレクト URL の構成
このセクションは管理者向けです。
kubectl のリダイレクト URL に加えて、Google Cloud コンソール用のリダイレクト URL が必要です。Google Cloud コンソールのリダイレクト URL は次のとおりです。
https://console.cloud.google.com/kubernetes/oidc
OIDC プロバイダを構成するときに、リダイレクト URL の 1 つとして、https://console.cloud.google.com/kubernetes/oidc を指定します。方法はプロバイダによって異なります。
OpenID プロバイダへのクライアント アプリケーションの登録
このセクションは管理者向けです。
従業員が OpenID プロバイダで OIDC 用 Kubectl プラグインまたは Google Cloud コンソールを使用するには、その 2 つのクライアントをその OpenID プロバイダに登録する必要があります。登録手順は以下のとおりです。
プロバイダの発行者 URI を確認します。ここから、OIDC 用 Kubectl プラグインまたは Google Cloud コンソールが認証リクエストを送信します。
プロバイダに、OIDC 用 Kubectl プラグインのリダイレクト URL を指定します。
プロバイダに Google Cloud コンソール用のリダイレクト URL を提供します。この URL は https://console.cloud.google.com/kubernetes/oidc です。
単一のクライアント ID を設定します。プロバイダが OIDC 用と Google Cloud コンソール用の両方の Kubectl プラグインを識別するために使用する ID です。
単一のクライアント シークレットを設定します。OIDC と Google Cloud コンソール用の Kubectl プラグインはどちらもこの Secret を OpenID プロバイダの認証に使用します。
OIDC または Google Cloud コンソール用の 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 と Google Cloud コンソール用の Kubectl プラグインを例とするクライアント アプリケーションは、この URL に認可リクエストを送信します。Kubernetes API サーバーは、この URL を使用してトークン検証用の公開鍵を検出します。HTTPS を使用する必要があります。clientid
: 必須。OpenID プロバイダへの認証リクエストを行うクライアント アプリケーションの ID。OIDC 用と Google Cloud コンソール用の両方の Kubectl プラグインでこの ID が使用されます。clientsecret
: 省略可。クライアント アプリケーション用の Secret。OIDC 用と Google Cloud コンソール用の両方の Kubectl プラグインでこの Secret が使用されます。username
: 省略可。ユーザー名として使用する JWT クレーム。デフォルトはsub
で、これはエンドユーザーの一意の識別子である必要があります。OpenID プロバイダによっては、email
やname
などの他のクレームを選択できます。ただし、他のプラグインとの競合を避けるため、email
以外のクレームには発行者の URL が先頭に付加されます。usernameprefix
: 省略可。既存の名前と競合しないように、ユーザー名のクレームの先頭に付加される接頭辞。このフィールドを指定せず、username
がemail
以外の値の場合、接頭辞はデフォルトのissuerurl#
になります。値-
を使用すると、すべての接頭辞を無効にできます。group
: 省略可。プロバイダがセキュリティ グループを返すために使用する JWT クレーム。groupprefix
: 省略可。既存の名前と競合しないように、グループ クレームの先頭に付加される接頭辞。たとえば、グループfoobar
と接頭辞gid-
が指定されている場合、gid-foobar
となります。scopes
: 省略可。OpenID プロバイダにカンマ区切りのリストとして送信する追加のスコープ。extraparams
: 省略可。OpenID プロバイダにカンマ区切りのリストとして送信する追加の Key-Value パラメータ。- 認証パラメータのリストについては、認証 URI パラメータをご覧ください。
- Microsoft Azure の認証パラメータの一覧については、ログイン リクエストを送信するをご覧ください。
- グループを承認する場合は、
resource=token-groups-claim
を渡します。 - 認可サーバーが同意を求めるプロンプトを表示する場合は、
prompt=consent
を渡します。
usehttpproxy
: 省略可。ユーザー認証用の Connect Agent がオンプレミスの OIDC プロバイダにアクセスできるようにするため、クラスタにリバース プロキシをデプロイするかどうかを指定します。値は文字列("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 プラグインのクライアント シークレットです。
- [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 ペアのリストです。- 認証パラメータのリストについては、認証 URI パラメータをご覧ください。
- グループを承認する場合は、
resource=token-groups-claim
を渡します。 - 認可サーバーが同意を求めるプロンプトを表示する場合は、
prompt=consent
を渡します。
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 ペアのリストです。- Google の認証パラメータの一覧については、認証 URI パラメータをご覧ください。
- Microsoft Azure の認証パラメータの一覧については、ログイン リクエストを送信するをご覧ください。
- グループを承認する場合は、
resource=token-groups-claim
を渡します。 - 認可サーバーが同意を求めるプロンプトを表示する場合は、
prompt=consent
を渡します。
このコマンドを実行すると、client-config.yaml
というクライアント認証構成ファイルが生成されます。このファイルは手動で編集しないでください。
OIDC 用 Kubectl プラグインを使用したユーザー クラスタに対する認証
このセクションは、ユーザー クラスタを作成し、OIDC 用の Kubectl プラグインを使用する従業員を対象としています。
-
client-config.yaml
ファイルを使用してプラグインを初期化します。kubectl oidc login --clientconfig-file=client-config.yaml --user [NAME] \ --kubeconfig [KUBECONFIG_OUTPUT_PATH]
ここで
- [NAME] は、ユーザー名です。
- [KUBECONFIG_OUTPUT_PATH] は、OIDC 用 Kubectl プラグインが認証情報を保存している kubeconfig ファイルのパスです。
kubectl oidc login
で、認証情報を入力できるブラウザを起動します。現在指定されている kubeconfig ファイルには、kubectl でユーザー クラスタ上の Kubernetes API サーバーに認証するために使用される ID トークンが含まれています。
注: Windows ユーザーは、
kubectl oidc login
ではなくkubectl-oidc.exe
login コマンドの実行が必要になる場合があります。 -
認証が成功したことを確認するには、
kubectl
コマンドを実行します。例:kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]
Google Cloud Console での OIDC の使用
このセクションは、ユーザー クラスタを作成し、Google Cloud Console を使用してクラスタに対して認証を行う従業員を対象としています。
-
クラスタが OIDC 用に構成されていることを確認します。
-
クラスタが、自動でクラスタ作成中に、または手動で Google Cloud で登録されていることを確認します。
-
Google Cloud コンソールの [Kubernetes クラスタ] ページにアクセスします。
-
クラスタのリストで、GKE On-Prem クラスタを見つけ、[ログイン] をクリックします。
-
[クラスタ用に構成された ID プロバイダで認証] を選択し、[ログイン] をクリックします。
ID プロバイダにリダイレクトされます。ここで、ログイン、または Google Cloud コンソールがアカウントにアクセスすることへの同意が必要となる場合があります。その後、Google Cloud コンソールの [Kubernetes クラスタ] ページに再度リダイレクトされます。
GKE On-Prem における OIDC のトラブルシューティング
無効な構成
Google Cloud コンソールでクラスタから OIDC 構成を読み取れない場合、[ログイン] ボタンは無効になります。
無効なプロバイダ構成
ID プロバイダの構成が無効な場合は、[ログイン] をクリックした後に、ID プロバイダからのエラー画面が表示されます。プロバイダ固有の手順に従って、プロバイダまたはクラスタを正しく構成します。
無効な権限
認証フローを完了してもクラスタの詳細が表示されない場合は、OIDC で使用したアカウントに適切な RBAC 権限が付与されていることを確認してください。これは、Google Cloud コンソールへのアクセスに使用するアカウントとは異なる場合があるので注意してください。
Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct
このエラーは、認可サーバーから同意を求められたものの、必要な認証パラメータが指定されていない場合に発生します。prompt=consent
パラメータを GKE On-Prem 構成ファイルの oidc: extraparams
フィールドに指定し、--extra-params prompt=consent
フラグを使用してクライアント認証ファイルを再生成します。