外部OpenID Connect (OIDC)アイデンティティ・プロバイダを使用したクラスタ・ユーザーの認証

外部OpenID Connect (OIDC)アイデンティティ・プロバイダを使用して、Kubernetes Engine (OKE)で作成したクラスタのユーザーを認証する方法をご紹介します。

デフォルトでは、Kubernetes Engineを使用して作成するクラスタは、Oracle Cloud Infrastructure Identity and Access Management (OCI IAM)を使用してユーザーを認証します。OCI IAMとKubernetes RBAC Authorizerは連携して機能することで、少なくとも1人によって正常に認可されたユーザーは、リクエストされたKubernetes操作を完了できます。アクセス制御およびKubernetes Engine (OKE)についてを参照してください。

OCI IAMに加えて、Kubernetes Engineを使用して作成するクラスタで、外部OpenID Connect (OIDC)アイデンティティ・プロバイダ(IdP)を使用してユーザーを認証するように指定できます。クラスタごとに異なるOIDCアイデンティティ・プロバイダを指定できます。ユーザー認証に外部OIDCアイデンティティ・プロバイダ(Keycloakなど)を使用すると、OCI IAMで新しいユーザー・アカウントを作成するのではなく、組織がすでに保持している既存のアイデンティティ・プロバイダを利用できます。また、ユーザーはOCI IAMで定義されていないため、クラスタにのみアクセスでき、他のOCIリソースにはアクセスできません。

OIDC認証のクラスタを有効にすると、クラスタはOIDC認証プラグインを使用して、指定されたOIDCアイデンティティ・プロバイダでユーザーを認証します。要約すると、認証フローは次のとおりです。

ユーザーはOIDCアイデンティティ・プロバイダにログインしてid_tokenを取得します。
ユーザーがkubectlコマンドをクラスタに発行し、id_tokenを引数として渡します。
クラスタで実行されているKubernetes APIサーバーは、OIDCアイデンティティ・プロバイダの情報を使用してid_tokenを検証します。
Kubernetes APIサーバーは、Kubernetes RBAC認可を実行します。
ユーザーが認可されている場合、Kubernetes APIサーバーはリクエストされた操作を実行し、kubectlはユーザーにレスポンスを返します。

KubernetesのOIDC認証フローの詳細は、KubernetesドキュメントのOpenID Connectトークンを参照してください。

OIDC認証のクラスタを有効にした場合、Kubernetes RBAC Authorizerを使用して、特定のクラスタ上のユーザーに対して追加のファイングレイン・アクセス制御を適用することもできます。アクセス制御およびKubernetesエンジン(OKE)についての説明に従って、OCI IAM認証を使用する場合と同じ方法でKubernetes RBACロールおよびclusterroleを設定できます。ただし、Kubernetes RBACロールバインディングまたはclusterrolebindingを定義してロールまたはclusterroleをユーザーまたはグループにマップする場合は、OCI IAMで定義されたOCIDを指定するかわりに、外部OIDCアイデンティティ・プロバイダで定義されたユーザーまたはグループの名前を指定します。

次の点に注意してください:

仮想ノード、管理対象ノードおよび自己管理ノードを持つクラスタに対してOIDCアイデンティティ・プロバイダを指定できます。
OIDC認証が有効になっている場合でも、OCI IAM認証は常に有効です。そのため、OCI IAMユーザーとOIDCユーザーの両方を同じクラスタで認証し、認可されているクラスタで操作を実行できます。
Kubernetes EngineはOIDCクライアントを実装しません。外部OIDCアイデンティティ・プロバイダでユーザー認証の詳細を設定および保守し、アイデンティティ・プロバイダからid_tokenを取得するのはユーザーの責任です。
kubernetes-apiserverログを使用して、OIDCオーセンティケータ・プラグインの開始に関する問題およびトークン検証の問題をトラブルシューティングします。詳細は、Kubernetes Engine (OKE)サービス・ログの表示を参照してください。

OIDC認証の前提条件

OIDC認証でクラスタを有効化するための次の前提条件に注意してください。

クラスタは拡張クラスタである必要があります。OIDC認証は、基本クラスタではサポートされていません。
クラスタは、新しいクラスタまたはVCNネイティブ・クラスタである必要があります。つまり、Kubernetes APIエンドポイントが独自のVCNに統合されているクラスタです(VCNネイティブ・クラスタへの移行を参照)。OIDC認証は、独自のVCNに統合されていないKubernetes APIエンドポイントを持つクラスタではサポートされていません。
クラスタでKubernetesバージョン1.21 (またはそれ以降)が実行されている必要があります。

OIDC対応クラスタにアクセスするための次の前提条件に注意してください。

外部OIDCアイデンティティ・プロバイダにユーザー認証詳細が存在する必要があります。

外部OIDCアイデンティティ・プロバイダのIPアドレスおよびポート番号へのトラフィックを許可するクラスタのKubernetes APIエンドポイント・サブネットにエグレス・ルールが存在する必要があります:


状態:	宛先	プロトコル/宛先ポート	説明:
ステートフル	アイデンティティ・プロバイダのIPアドレス	アイデンティティ・プロバイダに依存します。	外部OIDCアイデンティティ・プロバイダへのトラフィックを許可します。

OIDC認証のクラスタの有効化

Kubernetesエンジンで作成したクラスタがOIDCアイデンティティ・プロバイダでユーザーを認証できるようにするには、クラスタのOIDC発行者URLおよびOIDCクライアントIDプロパティを少なくとも設定する必要があります。

また、オプションで、他のプロパティを設定してOIDC認証を制御することもできます。プロパティの完全なリストは、KubernetesドキュメントのAPIサーバーの構成を参照してください。

CLIを使用した外部OpenID Connect (OIDC)アイデンティティ・プロバイダの指定

CLIの使用の詳細は、コマンド・ライン・インタフェース(CLI)を参照してください。CLIコマンドで使用できるフラグおよびオプションの完全なリストは、コマンドライン・リファレンスを参照してください。

クラスタの作成および外部OpenID Connect (OIDC)アイデンティティ・プロバイダの指定

CLIを使用して、外部OpenID Connect (OIDC)アイデンティティ・プロバイダを使用する拡張クラスタを作成するには、oci ce cluster createコマンドを使用し、OIDC構成に必要な少なくとも次のパラメータを含めます:

--open-id-connect-auth-enabledをtrueに設定
--oidc-issuer-urlは、Kubernetes APIサーバーが公開署名キーを検出できるようにするアイデンティティ・プロバイダのベース公開URLに設定されます。これは通常、アイデンティティ・プロバイダのOIDC検出URLで、空のパスに変更されます。たとえば、発行者のOIDC検出URLがhttps://accounts.provider.example/.well-known/openid-configurationの場合、https://accounts.provider.exampleを指定します
--oidc-client-idは、すべてのトークンを発行する必要があるクライアントIDに設定されます。たとえば、kubernetesです。

例:

oci ce cluster create \
--compartment-id ocid1.compartment.oc1..aaaaaaaa______n5q \
--name sales \
--vcn-id ocid1.vcn.oc1.phx.aaaaaaaa______lhq \
--type ENHANCED_CLUSTER \
--kubernetes-version v1.25.4 \
--service-lb-subnet-ids "[\"ocid1.subnet.oc1.phx.aaaaaaaa______g7q"]" \
--endpoint-subnet-id ocid1.subnet.oc1.phx.aaaaaaaa______sna \
--endpoint-public-ip-enabled true \
--endpoint-nsg-ids "[\"ocid1.networksecuritygroup.oc1.phx.aaaaaaaa______5qq\"]" \
--cluster-pod-network-options '[{"cniType":"OCI_VCN_IP_NATIVE"}]' \
--open-id-connect-auth-enabled true
--oidc-issuer-url https://accounts.provider.example
--oidc-client-id kubernetes

クラスタのOIDC発行者URLおよびOIDCクライアントIDプロパティに加えて、オプションで他のプロパティを設定してOIDC認証を制御できます。プロパティの完全なリストは、KubernetesドキュメントのAPIサーバーの構成を参照してください。

クラスタの更新および外部OpenID Connect (OIDC)アイデンティティ・プロバイダの指定

CLIを使用して、外部OpenID Connect (OIDC)アイデンティティ・プロバイダを使用するように既存の拡張クラスタを更新するには:

任意のJSONエディタを使用して、JSON形式で新しいファイルを作成し、クラスタの外部OIDCアイデンティティ・プロバイダ構成を更新し、少なくとも構成に必要な次のパラメータを含めます:
```
{
"options": {
    "openIdConnectTokenAuthenticationConfig": {
      "isOpenIdConnectAuthEnabled": true,
      "issuerUrl": "<idp-base-url>",
      "clientId": "<client-id>"
      ]
    }
    }
}
```
ここでは:
- isOpenIdConnectAuthEnabledはtrueに設定されています
- "issuerUrl": "<idp-base-url>"は、Kubernetes APIサーバーが公開署名キーを検出できるようにするアイデンティティ・プロバイダのベース公開URLです。これは通常、アイデンティティ・プロバイダのOIDC検出URLで、空のパスに変更されます。たとえば、発行者のOIDC検出URLがhttps://accounts.provider.example/.well-known/openid-configurationの場合、https://accounts.provider.exampleを指定します
- "clientId": "<client-id>"は、すべてのトークンを発行する必要があるクライアントIDです。たとえば、kubernetesです。
例:
```
{
"options": {
    "openIdConnectTokenAuthenticationConfig": {
      "isOpenIdConnectAuthEnabled": true,
      "issuerUrl": "https://accounts.provider.example",
      "clientId": "kubernetes"
      ]
    }
    }
}
```
クラスタのOIDC発行者URLおよびOIDCクライアントIDプロパティに加えて、オプションで他のプロパティを設定してOIDC認証を制御できます。例:
```
{
"options": {
    "openIdConnectTokenAuthenticationConfig": {
      "clientId": "kubernetes",
      "usernameClaim": "sub",
      "issuerUrl": "https://token.actions.githubusercontent.com",
      "isOpenIdConnectAuthEnabled": true,
      "usernamePrefix": "actions-oidc:",
      "requiredClaim": [
        "repository=GH_ACCOUNT/REPO", 
        "ref=refs/heads/main"
      ]
    }
    }
}
```
プロパティの完全なリストは、KubernetesドキュメントのAPIサーバーの構成を参照してください。
外部OpenID Connect (OIDC)アイデンティティ・プロバイダ構成を含むJSONファイルを、名前および選択した場所に保存します。たとえば、/users/jdoe/update-oidc-configのようになります。

oci ce cluster updateコマンドを使用して、既存のクラスタを更新します。

oci ce cluster update --cluster-id <cluster-ocid> --from-json file://<path-to-file>

例:

oci ce cluster update --cluster-id ocid1.cluster.oc1.iad.aaaaaaaaaf______jrd --from-json file:///users/jdoe/update-oidc-config

APIを使用した外部OpenID Connect (OIDC)アイデンティティ・プロバイダの指定

CreateCluster操作を実行してクラスタを作成し、次の必須属性を含むopenIdConnectTokenAuthenticationConfigプロパティの属性の値を指定します。

isOpenIdConnectAuthEnabledをtrueに設定
issuerUrlは、Kubernetes APIサーバーが公開署名キーを検出できるようにするアイデンティティ・プロバイダのベース公開URLに設定されます。これは通常、アイデンティティ・プロバイダのOIDC検出URLで、空のパスに変更されます。たとえば、発行者のOIDC検出URLがhttps://accounts.provider.example/.well-known/openid-configurationの場合、https://accounts.provider.exampleを指定します
clientIdは、すべてのトークンを発行する必要があるクライアントIDに設定されます。たとえば、kubernetesです。

OIDC対応クラスタへのアクセス

外部OIDCアイデンティティ・プロバイダでユーザーを認証するクラスタにアクセスする1つの方法は、OIDCオーセンティケータを使用することです。OIDC認証プロバイダを使用してOIDC対応クラスタにアクセスするには、この項の説明に従って、ユーザー、OIDCアイデンティティ・プロバイダおよびOIDCトークンの詳細をkubeconfigファイルに入力する必要があります。または、--tokenオプションを使用して、kubectlコマンドにトークンを直接含めることで、OIDC対応クラスタにアクセスできます。OIDCオーセンティケータまたはkubectlの--tokenオプションの使用方法の詳細は、KubernetesドキュメントのOpenID Connectトークンを参照してください。

OIDC対応クラスタにアクセスする方法は他にもあります。たとえば、kubeloginなどのkubectlプラグインを使用します(詳細は、GitHubのkubeloginドキュメントを参照してください)。

OIDC認証プロバイダを使用してOIDC対応クラスタにアクセスするには:

外部OIDCアイデンティティ・プロバイダにログインします。
OIDCアイデンティティ・プロバイダが提供するid_tokenおよびrefresh_tokenをノートにとります。
必要に応じて、クラスタへのアクセス方法に応じて、クラスタへのクラウド・シェル・アクセスの設定またはクラスタへのローカル・アクセスの設定の手順に従って、OIDC対応クラスタにアクセスするためのkubeconfigファイルを設定します。
次のコマンドを実行して、外部OIDCアイデンティティ・プロバイダで認証されるユーザーをkubeconfigファイルに定義します:
```
kubectl config set-credentials <username> \
    --auth-provider=oidc \
    --auth-provider-arg=idp-issuer-url=<base-url> \
    --auth-provider-arg=client-id=<client-name> \
    --auth-provider-arg=client-secret=<client-secret> \
    --auth-provider-arg=refresh-token=<refresh-token> \
    --auth-provider-arg=id-token=<id-token> \
    --auth-provider-arg=extra-scopes=groups
```
ここでは:
- 外部OIDCアイデンティティ・プロバイダで認証するユーザーの<username>。たとえば、oidc-admin-user
- idp-issuer-url=<base-url>は、Kubernetes APIサーバーが公開署名キーを検出できるようにする外部OIDCアイデンティティ・プロバイダのベース公開URLです。これは通常、アイデンティティ・プロバイダのOIDC検出URLで、空のパスに変更されます。たとえば、発行者のOIDC検出URLがhttps://accounts.provider.example/.well-known/openid-configurationの場合、https://accounts.provider.exampleを指定します
- client-id=<client-name>は、クライアント資格証明の一部を形成するOIDCクライアントに関連付けられた文字列識別子です。たとえば、client-id=kubernetesです。
- client-secret=<CLIENT_SECRET>はシークレット文字列で、事実上クライアント資格証明のパスワードです。
- refresh-token=<refresh-token>は、認証後に外部OIDCアイデンティティ・プロバイダによって提供されるOAuth 2.0リフレッシュ・トークンです。
- id-token=<id-token>は、認証後に外部OIDCアイデンティティ・プロバイダによって提供されるOAuth 2.0 id_tokenです。id_tokenは、OIDC認証によるクラスタ・アクセスを許可するIdPユーザーを表します。
- extra-scopes=groupsは、トークンがリフレッシュされたときに外部OIDCアイデンティティ・プロバイダからリクエストする追加のOAuth 2.0スコープのリストです。
例:
```
kubectl config set-credentials oidc-admin-user \
    --auth-provider=oidc \
    --auth-provider-arg=idp-issuer-url=https://accounts.provider.example \
    --auth-provider-arg=client-id=kubernetes \
    --auth-provider-arg=client-secret=1db158______c5 \
    --auth-provider-arg=refresh-token=q1b______KtQA= \
    --auth-provider-arg=id-token=eyJr______4knw \
    --auth-provider-arg=extra-scopes=groups
```
次のコマンドを実行して、外部OIDCアイデンティティ・プロバイダを使用して認証される新規ユーザーのコンテキストをkubeconfigファイルに定義します。
```
kubectl config set-context <context-name> --cluster=<cluster-name> --user=<oidc-username>
```
ここでは:
- <context-name>は、コンテキストに対して選択した名前です。例: OIDC-auth
- --cluster=<cluster-name>は、OIDC対応クラスタの名前です。例: OIDC-development
- --user=<oidc-username>は、外部OIDCアイデンティティ・プロバイダで認証するユーザーの名前です。たとえば、oidc-admin-user
例:
```
kubectl config set-context OIDC-auth --cluster=OIDC-development --user=oidc-admin-user
```

Oracle Cloud Infrastructureドキュメント