第8章 外部 OIDC アイデンティティープロバイダーによる直接認証の有効化
トークンベースの認証に外部 OpenID Connect (OIDC)アイデンティティープロバイダーを直接使用するように OpenShift Container Platform を設定し、ビルトイン OAuth サーバーを組織の既存の ID インフラストラクチャーに置き換えます。
8.1. 外部 OIDC アイデンティティープロバイダーを使用した直接認証 リンクのコピーリンクがクリップボードにコピーされました!
外部の OpenID Connect (OIDC) アイデンティティープロバイダーとの直接統合を有効にして、認証用のトークンを発行できます。これにより、組み込みの OAuth サーバーがバイパスされ、外部アイデンティティープロバイダーが直接使用されます。
外部 OIDC プロバイダーと直接統合することで、組み込みの OAuth サーバーの機能に制限されることなく、お好みの OIDC プロバイダーの高度な機能を活用できます。組織は単一のインターフェイスからユーザーとグループを管理できるだけでなく、複数のクラスターやハイブリッド環境全体での認証を合理化できます。既存のツールやソリューションと統合することもできます。
現在、直接認証用に設定できる OIDC プロバイダーは 1 つだけです。
直接認証に切り替えると、既存の認証設定の保持は保証されません。直接認証を有効にする前に、認証にビルトイン OAuth サーバーの使用に戻る必要がある場合に備えて、既存のユーザー、グループ、oauthclient、またはアイデンティティープロバイダーの設定をバックアップします。
組み込みの OAuth サーバーを外部プロバイダーに置き換える前に、たとえば以下のいずれかのような、クラスター管理者権限で長期的にログインできる方法にアクセスできることを確認してください。
-
証明書ベースのユーザー
kubeconfigファイル (たとえばインストールプログラムによって生成されたファイルなど) -
有効期間の長いサービスアカウントトークン
kubeconfigファイル -
証明書ベースのサービスアカウント
kubeconfigファイル
外部アイデンティティープロバイダーに問題がある場合は、緊急の状況で OpenShift Container Platform クラスターにアクセスするためにこれらの方法のいずれかが必要です。
8.1.1. 無効化された OAuth リソース リンクのコピーリンクがクリップボードにコピーされました!
直接認証を有効にすると、いくつかの OAuth リソースが意図的に削除されます。
直接認証を設定する前に、削除されたリソースに依存していないことを確認してください。
直接認証が設定されている場合、次のリソースは使用できません。
- OpenShift OAuth サーバーと OpenShift OAuth API サーバー
-
ユーザーおよびグループ API (
*.user.openshift.io) -
OAuth API (
*.oauth.openshift.io) - OAuth サーバーとクライアントの設定
8.1.2. 直接認証アイデンティティープロバイダー リンクのコピーリンクがクリップボードにコピーされました!
直接認証は、複数の OpenID Connect (OIDC)アイデンティティープロバイダーでテストされ、クラスターを設定する前に互換性を検証するのに役立ちます。
以下のアイデンティティープロバイダーがテスト済みです。
- Windows Server 向けの Active Directory Federation サービス
- GitLab
- Keycloak
- Microsoft Entra ID
- Okta
- Ping Identity
- Red Hat Single Sign-On
Red Hat は、サードパーティーのアイデンティティープロバイダー機能に関連するすべての要因をテストするわけではありません。
8.2. 直接認証用に外部 OIDC アイデンティティープロバイダーを設定する リンクのコピーリンクがクリップボードにコピーされました!
OpenShift Container Platform を設定して、外部の OIDC アイデンティティープロバイダーを使用して直接認証を行うようにします。これにより、ユーザーは既存の企業認証情報を使用してログインでき、組み込みの OAuth サーバーをバイパスして、効率的なシングルサインオンを実現できます。
前提条件
外部認証プロバイダーを設定した。
この手順では、Keycloak をアイデンティティープロバイダーとして使用し、以下のクライアントが設定されていることを前提としています。
-
有効なリダイレクト URI が
https://<openshift_console_route>/auth/callbackに設定されたconsole-testという Web コンソールの機密クライアント -
有効なリダイレクト URI が
http://localhost:8080に設定された、oc-cli-testという OpenShift CLI (oc) の公開クライアント
-
有効なリダイレクト URI が
-
クラスターのインストールプログラムによって生成された
kubeconfigファイルにアクセスできる。 - 認証に組み込みの OAuth サーバーを使用するように戻す必要がある場合に備えて、既存の認証設定をバックアップした。
クラスター上で OpenShift Container Platform の Web コンソールが有効になっている。
注記クラスターで Web コンソールが有効になっていない場合は、Web コンソールクライアントを使用しない設定例について、「CLI クライアント専用の OIDC プロバイダー設定例」を参照してください。
手順
-
インストールプログラムによって生成された
kubeconfigファイル、またはクラスター管理者としてログインする別の長期的な方法を使用していることを確認します。 次のコマンドを実行して、Web コンソールでの認証を可能にするシークレットを作成します。
$ oc create secret generic console-secret \ --from-literal=clientSecret=<secret_value> \ -n openshift-config<secret_value>は、アイデンティティープロバイダーのconsole-testクライアントのシークレット値に置き換えます。オプション: 次のコマンドを実行して、プロバイダーの認証局バンドルを含む config map を作成します。
$ oc create configmap keycloak-oidc-ca --from-file=ca-bundle.crt=my-directory/ca-bundle.crt \ -n openshift-configプロバイダーの
ca-bundle.crtファイルへのパスを指定します。次のコマンドを実行して認証設定を編集します。
$ oc edit authentication.config/clustertypeフィールドをOIDCに設定し、プロバイダーのoidcProvidersフィールドを設定し、webhookTokenAuthenticatorフィールドをnullに設定して、認証設定を更新します。apiVersion: config.openshift.io/v1 kind: Authentication metadata: # ... spec: type: OIDC webhookTokenAuthenticator: null oidcProviders: - claimMappings: extra: - key: example.com/role valueExpression: claims.?role.orValue("unknown") groups: claim: groups prefix: 'oidc-groups-test:' uid: claim: "sub" username: claim: email prefixPolicy: Prefix prefix: prefixString: 'oidc-user-test:' issuer: audiences: - console-test - oc-cli-test issuerCertificateAuthority: name: keycloak-oidc-ca issuerURL: https://keycloak-keycloak.apps.example.com/realms/master name: 'keycloak-oidc-server' oidcClients: - clientID: oc-cli-test componentName: cli componentNamespace: openshift-console - clientID: console-test clientSecret: name: console-secret componentName: console componentNamespace: openshift-console extraScopes: - email - profile各項目の説明:
spec.type-
認証タイプを指定します。外部 OIDC アイデンティティープロバイダーを使用することを示すには、
OIDCに設定する必要があります。 spec.webhookTokenAuthenticator-
Web フックトークンのオーセンティケーター設定を指定します。
typeがOIDCに設定されている場合はnullに設定する必要があります。 spec.oidcProviders- OIDC プロバイダーの設定を指定します。現在、OIDC プロバイダー設定は 1 つだけ許可されています。
spec.oidcProviders.claimMappings.extra- クラスターアイデンティティーの追加属性を構築するために使用されるマッピングを指定します。このフィールドは任意です。
spec.oidcProviders.claimMappings.groups.claim- クラスターアイデンティティーのグループ名を構築するためのクレーム名を指定します。
spec.oidcProviders.claimMappings.uid- クラスターアイデンティティーの UID を構築するために使用されるクレームマッピングを指定します。このフィールドは任意です。
spec.oidcProviders.claimMappings.username.claim- クラスターアイデンティティーのユーザー名を構築するためのクレームの名前を指定します。
spec.oidcProviders.issuer.audiences- この認証プロバイダーがトークンを発行する対象となるオーディエンスのリストを指定します。
spec.oidcProviders.issuer.issuerCertificateAuthority.name-
ca-bundle.crtキーを含む config map の名前を指定します。設定されていない場合は、代わりにシステム信頼が使用されます。 spec.oidcProviders.issuer.issuerURL- トークン発行者の URL を指定します。
spec.oidcProviders.name- 外部 OIDC プロバイダーの名前を指定します。
spec.oidcProviders.oidcClients.clientID-
プロバイダーが使用するクライアント ID を指定します。OpenShift CLI (
oc) と OpenShift Container Platform Web コンソール用に、それぞれ個別のエントリーを設定します。 spec.oidcProviders.oidcClients.clientSecret.name- コンソールクライアントのシークレット値を格納するシークレットの名前を指定します。
spec.oidcProviders.oidcClients.extraScopes- 要求する追加スコープを指定します。GitLab などの一部のプロバイダーでは、Web コンソールから適切にログインするために追加のスコープが必要になる場合があります。
- 終了して変更を保存し、新しい設定を適用します。
クラスターが新しいリビジョンをすべてのノードにロールアウトするまで待ちます。
次のコマンドを実行して、Kubernetes API server Operator のステータスを確認します。
$ oc get co kube-apiserver出力例
NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE kube-apiserver 4.21.0 True True False 85m NodeInstallerProgressing: 2 node are at revision 8; 1 node is at revision 10前の例のメッセージは、1 つのノードが新しいリビジョンに進み、2 つのノードがまだ更新されていないことを示しています。クラスターのサイズによっては、新しいリビジョンをすべてのノードにロールアウトするのに 20 分以上かかる場合があります。
-
問題をトラブルシューティングするために、Cluster Authentication Operator と
kube-apiserverPod のログでエラーを確認することもできます。
検証
アイデンティティープロバイダーで認証して、OpenShift CLI (
oc) にログインできることを確認します。次のコマンドを実行してログインします。
$ oc login --exec-plugin=oc-oidc \ --issuer-url=https://keycloak-keycloak.apps.example.com/realms/master \ --client-id=oc-cli-test \ --extra-scopes=email --callback-port=8080 \ --oidc-certificate-authority my-directory/ca-bundle.crt各項目の説明:
--exec-plugin-
実行プラグインの種類を指定します。
oc-oidcの値のみが許可されます。 --issuer-url- アイデンティティープロバイダーの発行者 URL を指定します。
--client-id-
OpenShift CLI (
oc) のクライアント ID を指定します。 --oidc- 認証局ローカルマシン上の
ca-bundle.crtファイルへのパスを指定します。出力例
Please visit the following URL in your browser: http://localhost:8080
- ブラウザーで http://localhost:8080 を開きます。
アイデンティティープロバイダーからの認証情報を使用して認証します。
認証に成功すると、ターミナルに次の出力のようなメッセージが表示されます。
Logged into "https://api.my-cluster.example.com:6443" as "oidc-user-test:user1@example.com" from an external oidc issuer.
アイデンティティープロバイダーで認証して、OpenShift Container Platform Web コンソールにログインできることを確認します。
ブラウザーでクラスターの Web コンソール URL を開きます。
ログインのために、アイデンティティープロバイダーにリダイレクトされます。
アイデンティティープロバイダーからの認証情報を使用して認証します。
正常にログインし、OpenShift Container Platform Web コンソールにリダイレクトされたことを確認します。
8.2.1. OIDC プロバイダーの設定パラメーター リンクのコピーリンクがクリップボードにコピーされました!
次の表には、直接認証に使用できるすべての OIDC プロバイダーパラメーターがリストされています。
| パラメーター | 説明 |
|---|---|
|
| Kubernetes API サーバーが、アイデンティティープロバイダーによって発行された JSON web token (JWT) 内のクレームをクラスターアイデンティティーに変換するために使用するルールを設定します。 |
|
| クラスターアイデンティティーの追加属性の構築に使用されるマッピングを設定するためのオプションフィールド。省略すると、クラスターアイデンティティーに追加の属性は存在しなくなります。追加マッピングのキー値は一意である必要があります。最大 32 個の追加属性マッピングを提供できます。 |
|
| 追加属性キーとして使用する文字列を指定する必須フィールド。以下の制限が適用されます。
|
|
|
JWT トークンのクレームから追加の属性値を抽出する CEL 式を指定するための必須フィールド。
|
|
| クラスターアイデンティティーのグループが、アイデンティティープロバイダーによって発行された JWT トークン内のクレームから構築される方法を設定します。クレームの参照時にクレームが JWT トークン内に存在する場合、その値はグループのコンマ区切りリストである必要があります。 |
|
| このマッピングに関連付けられたクラスターアイデンティティーフィールドに値が割り当てられる JWT トークンクレームを設定します。 |
|
| JWT クレームをクラスターアイデンティティー属性にマッピングするプロセス中にクラスターアイデンティティー属性に適用される接頭辞を設定します。 |
|
|
クラスターアイデンティティーの UID の構築に使用されるクレームマッピングを設定するためのオプションフィールド。省略すると、ユーザーによる指定なしとみなされ、プラットフォームによってデフォルトが選択されます。デフォルトは、今後変更される可能性があります。現在のデフォルトでは、 |
|
|
マッピングで使用される JWT トークン要求を指定するためのオプションフィールド。このクレームの値は、このマッピングが関連付けられているフィールドに割り当てられます。クレームを指定するには、
|
|
|
JWT トークンクレームから文字列値を生成する CEL 式を指定するためのオプションフィールド。
CEL 式は、CEL 変数
|
|
| アイデンティティープロバイダーによって発行された JWT トークン内のクレームからクラスターアイデンティティーのユーザー名を構築する方法を設定します。 |
|
| このマッピングに関連付けられたクラスターアイデンティティーフィールドに値が割り当てられる JWT トークンクレームを設定します。 |
|
|
JWT クレームの値の先頭に追加する接頭辞を設定します。 |
|
|
JWT クレームをクラスターアイデンティティーユーザー名属性にマッピングするプロセス中にクラスターアイデンティティー属性に適用される接頭辞を設定します。空の文字列 ( |
|
|
省略すると、指定なしとみなされ、プラットフォームによって選択された接頭辞が適用されます。ただし、これは今後変更される可能性があります。
現時点では、クレームが |
|
|
アイデンティティープロバイダーによって発行された JWT トークン内のクレームを検証するために Kubernetes API サーバーが使用するルールを設定します。検証ルールは |
|
| Kubernetes API サーバーが、受信 JWT がこのアイデンティティープロバイダーに対して有効かどうかを検証するために使用する、必須のクレームと値を設定します。 |
|
|
必須クレームの名前を設定します。JWT クレームから取得する場合、クレームは文字列の値である必要があります。空の文字列 ( |
|
|
受信した JWT クレームから取得した場合に |
|
|
検証ルールのタイプを設定します。許可される値は
|
|
| プラットフォームがアイデンティティープロバイダーと対話する方法と、アイデンティティープロバイダーから発行されたトークンが Kubernetes API サーバーによって評価される方法を設定する必須フィールド。 |
|
|
アイデンティティープロバイダーによって発行される JWT トークンの発行先として許可されるオーディエンスを設定する必須フィールド。エントリーの少なくとも 1 つは、JWT トークンの |
|
|
Kubernetes API サーバーが使用する認証局を設定して、検出情報を取得するときにアイデンティティープロバイダーへの接続を検証します。指定しない場合は、システム信頼が使用されます。指定する場合は、config map の |
|
| 参照される config map の名前。 |
|
|
アイデンティティープロバイダーによってトークンを発行するために使用される URL を設定します。Kubernetes API サーバーは、JWT の |
|
|
アイデンティティープロバイダーに関連付けられた、人間が判読できる一意の識別子を設定する必須フィールド。複数のアイデンティティープロバイダーを区別するために使用され、トークンの検証や認証メカニズムには影響しません。空の文字列 ( |
|
| クラスター上のプラットフォームクライアントがアイデンティティープロバイダーからトークンを要求する方法を設定します。エントリーは 20 以下でなければならず、エントリーには一意の namespace/名前のペアが必要です。 |
|
|
プラットフォームコンポーネントがアイデンティティープロバイダーへの認証要求に使用する、アイデンティティープロバイダーからのクライアント ID を設定します。プラットフォームコンポーネントがアイデンティティープロバイダーを認証モードとして使用するためには、アイデンティティープロバイダーがこの識別子を受け入れる必要があります。空の文字列 ( |
|
| アイデンティティープロバイダーへの認証要求を行うときにプラットフォームコンポーネントによって使用されるクライアントシークレットを設定します。 指定しない場合、アイデンティティープロバイダーへの認証要求時にクライアントシークレットは使用されません。
指定すると、 パブリッククライアントにクライアントシークレットは必要ありませんが、プライベートクライアントにはアイデンティティープロバイダーと連携するためにクライアントシークレットが必要です。 |
|
| 参照されるシークレットの名前。 |
|
|
認証モードとしてアイデンティティープロバイダーを使用するように設定されているプラットフォームコンポーネントの名前を指定します。一意の識別子として、 |
|
|
認証モードとしてアイデンティティープロバイダーを使用するように設定されているプラットフォームコンポーネントが実行されている namespace を指定します。一意の識別子として、 |
|
| アイデンティティープロバイダーへの認証要求を行うときに、プラットフォームコンポーネントによって要求される追加のスコープを設定します。標準の OIDC スコープを超えて特定のスコープを要求するクレームマッピングを設定した場合に役立ちます。省略すると、追加のスコープは要求されません。 |
8.2.2. CLI クライアント専用の OIDC プロバイダー設定例 リンクのコピーリンクがクリップボードにコピーされました!
Web コンソールが無効になっている OpenShift Container Platform クラスターでは、CLI クライアントのみを対象に、外部 OIDC プロバイダーを使用した直接認証を設定できます。このような場合、ユーザーは Web コンソールではなく、OpenShift CLI (oc) を介してクラスターに直接認証する必要があります。
以下の OIDC プロバイダー設定例は、Web コンソールクライアントを定義せずに CLI クライアントを設定する方法を示しています。
CLI クライアントのみを使用した OIDC プロバイダー設定
apiVersion: config.openshift.io/v1
kind: Authentication
metadata:
# ...
spec:
type: OIDC
webhookTokenAuthenticator: null
oidcProviders:
- claimMappings:
groups:
claim: groups
prefix: 'oidc-groups-test:'
username:
claim: email
prefixPolicy: Prefix
prefix:
prefixString: 'oidc-user-test:'
issuer:
audiences:
- my-cli-client-id
issuerURL: my-issuer-url
name: my-oidc-provider-name
8.3. 直接認証の無効化 リンクのコピーリンクがクリップボードにコピーされました!
外部 OIDC 統合が不要になったときに、クラスターが認証に組み込みの OpenShift Container Platform OAuth サーバーを使用するように、直接認証を無効にします。
前提条件
-
クラスターのインストールプログラムによって生成された
kubeconfigファイルにアクセスできる。
手順
-
インストールプログラムによって生成された
kubeconfigファイル、またはクラスター管理者としてログインする別の長期的な方法を使用していることを確認します。 以下のコマンドを実行して、ビルトイン OpenShift Container Platform OAuth サーバーを使用するように認証設定を更新します。
$ oc patch authentication.config/cluster --type=merge -p=' spec: type: "" oidcProviders: null '各項目の説明:
spec.type-
認証タイプを指定します。組み込みの OpenShift Container Platform OAuth サーバーを使用するには、"
""に設定します。IntegratedOAuthも同じ値にします。 spec.oidcProviders-
OIDC プロバイダーの設定を指定します。外部 OIDC プロバイダーの設定を削除するには、
nullに設定してください。
クラスターが新しいリビジョンをすべてのノードにロールアウトするまで待ちます。
次のコマンドを実行して、Kubernetes API server Operator のステータスを確認します。
$ oc get co kube-apiserver出力例
NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE kube-apiserver 4.21.0 True True False 85m NodeInstallerProgressing: 2 node are at revision 12; 1 node is at revision 14前の例のメッセージは、1 つのノードが新しいリビジョンに進み、2 つのノードがまだ更新されていないことを示しています。クラスターのサイズによっては、新しいリビジョンをすべてのノードにロールアウトするのに 20 分以上かかる場合があります。
-
問題をトラブルシューティングするために、Cluster Authentication Operator と
kube-apiserverPod のログでエラーを確認することもできます。
- 必要に応じて、既存の認証設定を復元します。
検証
-
OpenShift Container Platform Web コンソールおよび OpenShift CLI (
oc) に正常にログインできることを確認します。