メインコンテンツまでスキップ

クラスターの OIDC 認証を構成する

チーム全体で 1 つの admin kubeconfig(client certificate)を共有する代わりに、クラスターを自社の既存の Identity Provider(IdP。Keycloak、Azure AD、Okta、または標準準拠の任意の OIDC provider)に接続できます。構成後は、各メンバーが自分の SSO アカウントでクラスターにログインします。

注記

この機能が扱うのは認証(authentication。ユーザーが誰であるかの確認)のみです。ユーザーが何をできるか(authorization)は、Kubernetes RBAC を使って自分で構成する必要があります。RBAC の例は SSO でクラスターにログインする を参照してください。OIDC を有効化した後、ログインに成功しても RoleBinding がないユーザーは kubectl get pods のようなコマンドで 403 Forbidden を受け取ります — これは設計どおりの動作であり、構成ミスではありません。

この構成は、すでに admin kubeconfig を持つ Cluster Admin が行います。適用してもクラスターの再起動やダウンタイムは発生せず、構成はいつでも更新・削除できます。

  1. SSO / OIDC セクションを開きます。

    構成したいクラスターの Cluster Detail を開き、Cluster Endpoint Access の下にある SSO / OIDC セクションまでスクロールします(構成するまで Status は Disabled と表示されます)。そこで Edit を選択します。

    Cluster Detail ページ、Essential Properties タブの SSO / OIDC セクション。beta と Optional バッジ、Status: Disabled、Edit ボタンを表示

  2. 基本的な接続情報を入力します。

    Edit を選択すると SSO / OIDC の構成フォームが開きますが、Enable SSO / OIDC トグルは既定で OFF になっています。トグルを ON にすると以下のフィールドが有効になります。その後、次を入力します。

    • Issuer URL(必須): Identity Provider の基本アドレス — クラスターがログイントークンの検証をリクエストする先です。https:// から始まる完全な URL を、末尾に ?(query string)や #(fragment)を付けずに入力します。通常は IdP の「Realm settings」または「OIDC discovery」ページからそのままコピーします。
      • Keycloak: https://keycloak.mycompany.com/realms/production
      • Azure AD: https://login.microsoftonline.com/{tenant-id}/v2.0
      • Okta: https://mycompany.okta.com/oauth2/default
    • Client ID(必須): IdP に登録した「アプリケーション」(このクラスター自身)の識別子 — 例えば Keycloak では Clients → Create client で作成します。値は 1 つのみ入力します。現時点では 1 クラスターに複数の Client ID を設定できません。
    • Username Claim(任意): ログイントークン内で Kubernetes の username として使うフィールド名。既定値は email です。代わりに sub(IdP 内部の ID。通常は読みにくい UUID 文字列)を使いたい場合は、このフィールドを空にしてください。時間が経っても変わらない安定した値の claim を選んでください — email が変わると、その値に基づく既存の RBAC binding が無効になります。
    • Groups Claim(任意): ユーザーが属する group の一覧を含むトークン内のフィールド名 — 個々のユーザーではなくグループ単位で権限を割り当てる場合に使います。よく使われる値は groups(Keycloak/Okta の既定)や client_roles(Keycloak の client roles)です。このクラスターでグループ単位の権限を使わない場合は空欄のままにします。

    SSO / OIDC フォームが開いた状態、トグル ON、Issuer URL / Client ID / Username Claim / Groups Claim の 4 フィールド

    ヒント

    クラスターの control plane が Issuer URL に到達できるネットワーク経路が必要です。IdP が社内ネットワークにある場合は、保存前にクラスターから到達できることを確認してください。

  3. 詳細設定を構成します(任意)。

    以下の 4 フィールドはすべて任意で、互いに独立しています — 1 つを入力しても、他のフィールドを入力する必要はありません。

    • Username Prefix: Kubernetes にマッピングする際に Username Claim の値の前に自動で付加される、通常 : で終わる短い文字列です。例えば oidc: を設定すると、email = an.nguyen@mycompany.com が Kubernetes の username oidc:an.nguyen@mycompany.com になります。これにより、SSO 経由でログインしたユーザーを system ユーザーや別の方法で作成されたユーザーと区別しやすくなります。system: で始めることはできません — この prefix は Kubernetes の system group 用に予約されています。空欄の場合、Kubernetes は claim の値をそのまま username として使うため、他のユーザーと重複するリスクがあります。
    • Groups Prefix: Username Prefix と同様の考え方で、group 名に適用されます — 例えば oidc: を設定すると、元の group platform-admins が Kubernetes 上で oidc:platform-admins になります。system: に関する制限は同じです。
    • CA Bundle (PEM): クラスターが IdP への HTTPS 接続を信頼するために使う CA 証明書です。IdP が自己署名証明書または社内 CA を使っている場合のみ必要です — IdP が Let's Encrypt や DigiCert などの public CA を使っている場合は空欄のままにします。.pem または .crt ファイルの内容全体を、-----BEGIN CERTIFICATE----- で始まり -----END CERTIFICATE----- で終わる正しい形式で貼り付けます。中間の本文は有効な base64 文字列である必要があります。
    • Required Claims: ログイントークンが満たすべき必須条件のリストです — IdP 上で有効なアカウントを持つユーザーでも、指定した claim に指定した値が含まれていなければログインを拒否します。+ Add claim を選択し、各行に Claim(トークン内のフィールド名)と Value(一致すべき値)を入力します。各行は両方の項目が必須で、同じ claim 名を複数行で指定することはできません。例: Claim hd、Value mycompany.com を設定すると、同じ IdP が個人の Gmail アカウントも扱っている場合でも、mycompany.com ドメインの Google Workspace アカウントのみがログインできます。

    Advanced セクションを展開した状態、Username Prefix / Groups Prefix / CA Bundle / Required Claims の 4 フィールド

  4. Save を選択します。

    変更が適用される間、クラスターは Processing 状態になります — Cluster Detail ページ上部の全体ステータスで進行状況を確認できます。クラスターが Succeeded/Running 状態に戻ると、構成が有効になります。

    SSO / OIDC 構成の Save ボタン

結果​

チームは kubelogin/OIDC プラグインを使う kubeconfig を取得し、共有の admin kubeconfig の代わりに自分の SSO アカウントでクラスターにログインできるようになります。生成される username または group(上で設定した prefix を含む)に対応する RBAC binding(RoleBinding/ClusterRoleBinding)は、admin kubeconfig を使って自分で作成する必要があります。この手順は Portal では自動化されません。

エンドユーザー側の設定手順と RBAC の例は SSO でクラスターにログインする を参照してください。

構成の更新・削除​

SSO / OIDC セクションの Edit はいつでも再度選択でき、既存の構成を変更できます。

  • 値を更新する — 任意のフィールドを変更し(例: IdP 変更後に Issuer URL や Client ID を更新)、Save を選択します。

  • 構成を削除する — Enable SSO / OIDC トグルを OFF にし、Save を選択します。Remove SSO / OIDC configuration? ダイアログが表示され、変更が適用されると(数分後)現在の OIDC ログインセッションがすべて機能しなくなること、admin kubeconfig(client certificate)には影響しないことが警告されます。続行するには Confirm removal を選択し、取りやめる場合は Cancel を選択します。

    Enable SSO / OIDC トグルを OFF にした状態で保存すると表示される Remove SSO / OIDC configuration 確認ダイアログ

構成を削除しても admin kubeconfig には影響しません — いつでも admin kubeconfig にフォールバックできます。

よくある問題​

問題原因 / 対処方法
"This feature isn't available for your account yet"アカウントに beta_user 権限がまだ付与されていません — FKE チームに連絡して登録してください。
Save や削除を選択したときに "This cluster is still processing"クラスターが別の変更を適用中です — 数分待ってから再試行してください。
構成が正しいのに SSO ログインが拒否されるRBAC binding が正確な username/group(prefix を設定している場合はそれも含む)に一致しているか、トークンに設定した Required Claims がすべて含まれているかを確認してください。
system: で始まる Prefix を入力できないこれは意図的な制限です — Kubernetes の system group との衝突を防ぎ、権限昇格のリスクを避けるためです。
フィールド(Issuer URL、CA Bundle など)が無効だがエラーメッセージが表示されない現在の beta 版の既知の制限です — フィールドが赤枠になるだけで説明文が表示されません。必須の形式(Issuer URL は query string や fragment なしの HTTPS、CA Bundle は正しい PEM 形式)を再確認してください。

ヒント​

  • 本番クラスターでチーム全体に適用する前に、まず staging クラスターで IdP との接続を試してください。
  • admin kubeconfig はフォールバックとして保持しておいてください — OIDC の有効化・無効化の影響を受けません。
  • Required Claims を使ってログインできる範囲を絞り込みます — 例えば hd = yourcompany.com を持つトークンのみを受け付けることで、同じ IdP を複数組織で共有している場合に社外のユーザーがログインするのを防げます。
  • Username Prefix を明確に設定します(例: oidc:)。ログや audit を確認する際に、SSO ユーザーを system ユーザーと区別しやすくなります。