Chaos and Order

💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

はじめに — ログインをなぜ自作してはいけないのか
第 1 部 — 4 つの中核概念で見る Keycloak
第 2 部 — OIDC ログインフローを 1 ステップずつ
第 3 部 — デプロイ: Quarkus 2 段階モデルと本番の落とし穴
第 4 部 — 2026 年の Keycloak: 26.x の新機能
第 5 部 — いつ使い、いつ考え直すか
おわりに
参考資料

はじめに — ログインをなぜ自作してはいけないのか

社内アプリが 20 個あるとします。それぞれに会員登録・パスワード再設定・2FA・ソーシャルログイン・セッション管理を別々に実装すれば、セキュリティホールが 20 倍になります。SSO(Single Sign-On)の発想はシンプルです — ログインという仕事を専任するサーバーを 1 つ置き、すべてのアプリがそのサーバーに「この人は誰か?」を委任するのです。ユーザーは一度ログインすれば 20 個のアプリをすべて使え、アプリはパスワードにいっさい触れません。

Keycloak は、このアイデンティティサーバーのオープンソース標準です(現在は CNCF インキュベーティングプロジェクトであり、Red Hat build of Keycloak のアップストリーム)。OIDC と SAML の両方を話し、ソーシャルログインのブローカリング・LDAP 連携・2FA・WebAuthn を標準で提供します。この記事では Keycloak を 4 つの中核概念 で理解し、ログインフローを 1 ステップずつ追ったうえで、デプロイの落とし穴と 2026 年の新機能まで整理します。認証フロー自体になじみがなければ、まず認証フロー可視化ツールを触ってみると、この記事がぐっと読みやすくなります。

第 1 部 — 4 つの中核概念で見る Keycloak

Keycloak の管理コンソールはメニューが数十個ありますが、骨組みは 4 つです。

概念               役割                                       たとえ
─────────────────  ─────────────────────────────────────────  ──────────────────
Realm              完全に隔離されたテナント(独自のユーザー・設定)  1 つの「王国」
Client             認証を委任されるアプリケーション             王国の「通行証の発行対象」
Role / Group       権限とユーザーのまとまり                     「役職」と「部署」
Identity Provider  外部ログインのソース(Google・上位 OIDC/SAML)  「別の王国のパスポートを承認」

Realm(レルム) は隔離の境界です。1 つの Realm には独自のユーザー・クライアント・ロール・ログイン設定が入り、ほかの Realm とは完全に分離されます。管理者アカウントが住む master Realm は Keycloak 自体を管理する用途のみに使い、実際のサービスは別の Realm を新たに切るのが定石です。「顧客ごとにユーザーを分けたい」なら最初に思い浮かぶ答えが Realm ですが — 後で見る Organizations のほうが適している場合が多いです。
Client(クライアント) は「認証を委任されるアプリ」です。ブラウザ上で動く SPA はシークレットを隠せないので public クライアント(+PKCE 必須)、バックエンドサーバーはシークレットを守れるので confidential クライアント です。各クライアントはプロトコル(OIDC または SAML)、許可された redirect URI、トークン寿命などを自身の設定として持ちます。
Role / Group は権限モデルです。Role は「役職」(admin、editor)、Group は「部署」(ユーザーのまとまり + 共通のロール・属性)です。ロールを別のロールに含める composite role で階層を作ることもできます。原則: ロールはアプリが理解する権限、グループは 人を組織する方法 として分けて考えてください。
Identity Provider(IdP) は「外部ログインのソース」です。Google・GitHub のソーシャルログイン、あるいは会社の上位 OIDC/SAML IdP をブローカリングして、Keycloak がその前に立つ仲介者になります。LDAP・Kerberos は IdP ではなく User Federation として接続します(ユーザーストアをそのまま読み込む)。

第 2 部 — OIDC ログインフローを 1 ステップずつ

もっともよく使うフローは Authorization Code + PKCE です。SPA が Keycloak にログインを委任する過程を追ってみましょう。

① ユーザーがアプリの「ログイン」をクリック
   → アプリがブラウザを Keycloak の authorize エンドポイントへリダイレクト
     (client_id、redirect_uri、scope=openid、code_challenge を含む)

② Keycloak がログイン画面を表示 → ユーザーが認証(パスワード + OTP など)
   ※ すでに Keycloak セッションがあればこの画面をスキップ = SSO の核心

③ Keycloak が redirect_uri へ返す + 使い捨ての authorization code

④ アプリのバックエンド(または SPA)が code + code_verifier を token エンドポイントで交換
   → access_token(JWT)+ id_token + refresh_token を受け取る

⑤ アプリは access_token を API 呼び出しの Authorization ヘッダーに載せて送る
   API は Keycloak の公開鍵(JWKS)で署名だけ検証 — リクエストごとに Keycloak に問い合わせない

ここで 3 つが核心です。第一に、PKCE(code_challenge/code_verifier)は盗まれた authorization code を無力化します — public クライアントなら必須です。第二に、②の「セッションがあればスキップ」がまさに SSO です。2 つ目のアプリがログインを委任すると、Keycloak はすでにブラウザの Cookie でユーザーを認識し、ログイン画面なしで即座に code を発行します。第三に、⑤で API はリクエストごとに Keycloak を呼びません — access_token は署名された JWT なので、公開鍵でローカル検証 するだけで済みます。この無状態性こそ SSO がスケールする理由です。

トークン 3 種の役割も混同しないでください。

id_token       「誰がログインしたか」— ユーザー情報。アプリ(クライアント)が消費
access_token   「何ができるか」— 権限。API(リソースサーバー)が検証
refresh_token  「再発行を受ける権利」— access_token 失効時の更新用、安全に保管

セッション・トークン寿命のチューニングは Realm 設定の中核レバーです。access_token は短く(数分)、refresh_token は長く(SSO セッション寿命まで)取るのが標準であり、短い access_token + ローカル署名検証の組み合わせが「盗まれてもすぐ失効」と「速い検証」を同時に与えます。

第 3 部 — デプロイ: Quarkus 2 段階モデルと本番の落とし穴

Keycloak 17 からディストリビューションは Quarkus ベースです(旧 WildFly/JBoss ディストリビューションは削除)。ここで初めて触る人がもっともよく引っかかる落とし穴が build/start 2 段階モデル です。

# ① ビルド段階(augmentation): DB ベンダー・有効な機能を「焼き込む」
#    — この段階は遅いが頻繁には行わない
bin/kc.sh build --db=postgres --features=organizations,token-exchange

# ② 実行段階: ランタイム設定(ホスト名・DB 接続・TLS)だけを渡す
bin/kc.sh start --optimized \
  --hostname=https://auth.example.com \
  --db-url=jdbc:postgresql://db/keycloak \
  --db-username=keycloak --db-password="$KC_DB_PASSWORD"

# ローカル開発用は 2 段階を合わせてくれる便利コマンド
bin/kc.sh start-dev

--optimized フラグは「すでに build したので start で再ビルドするな」という意味です。コンテナイメージでは、ビルド段階を Dockerfile に入れてイメージに焼き込んでおき、ランタイムでは start --optimized だけを走らせるのが定石です。

本番で踏む代表的な地雷が 3 つ。

hostname v2 — Keycloak 26 から hostname 設定が完全に変わりました。いまや --hostname にはホスト名の断片ではなく 完全な URL(https://auth.example.com)を与え、管理コンソールを別のアドレスで公開するには --hostname-admin を別途与えます。リバースプロキシの背後なら --proxy-headers=xforwarded も合わせて。誤って設定すると、リダイレクト URI が内部アドレスへ漏れ出したり、ログインループに陥ったりします。
本番モードは TLS を強制 — start(dev ではない)は HTTPS・hostname・DB がきちんとないと起動しません。プロキシが TLS を終端する場合は --proxy-headers で知らせないと、Keycloak が自身の外部アドレスを正しく認識できません。
DB がすなわち状態のすべて — Keycloak サーバー自体は無状態に近く、ユーザー・セッション・設定はすべて外部 DB(Postgres 推奨)にあります。そのため水平スケールが容易ですが、DB のバックアップ・マイグレーションがすなわちアイデンティティのバックアップです。

Kubernetes なら Keycloak Operator が Keycloak・KeycloakRealmImport CRD でこれらすべてを宣言的に包んでくれます。Kubernetes の感覚が必要なら、Kubernetes プレイグラウンドで CRD・オペレーターのパターンを先に身につけておくとよいです。

第 4 部 — 2026 年の Keycloak: 26.x の新機能

この記事の時点での最新は 26.6.3 です(内部 Quarkus 3.33.2)。26 系で正式機能となったもののうち、実務インパクトが大きい 4 つ。

Organizations — 26.0 で正式リリースされた「マルチテナンシーの正解」です。これまで「顧客ごとの隔離」は Realm を複数切るか、グループで模倣していましたが、どちらも痛みがありました(Realm は重く、グループは隔離が弱い)。Organizations は 1 つの Realm の中で 組織ごとのメンバー・ドメイン・専用 IdP を持ち、組織コンテキストでログインすると、そのメンバーシップが OIDC トークン・SAML アサーションに自動で載ります。26.x を経て、組織ごとに隔離されたグループ階層と、外部クレームに基づく自動グループ割り当て(IdP マッパー)まで備えました。「Realm は互いにまったく他人同士のシステム、Organizations は同じシステム内の複数の顧客」 と覚えてください。
JWT Authorization Grant (RFC 7523) — 外部で署名した JWT アサーションで Keycloak のアクセストークンを受け取る標準的な方式です。従来の「外部→内部トークン交換」を置き換える推奨経路であり、サービス間の信頼を標準プロトコルで築けるようにします。
Workflows — Realm の管理作業(例: 非アクティブユーザーの整理、特定イベントに応じた後続処理)を自動化する機能が正式化されました。これまでカスタム拡張や外部 cron で行っていた仕事が、サーバー機能として入ってきたものです。
無停止パッチリリース — パッチバージョン間のローリングアップデートがサポートされ、クラスターを止めずにセキュリティパッチを適用できます。アイデンティティサーバーは「絶対に落ちてはならない」インフラである点で、大きな前進です。

トークン交換(token exchange)にはまだ境界があります — 現在は OIDC/OAuth 交換のみをサポートし、SAML ベースのクライアント・IdP 交換は今後の課題です。そのため外部の信頼構築には、上の JWT Authorization Grant のほうがより標準的な答えです。

第 5 部 — いつ使い、いつ考え直すか

Keycloak が輝く場面: オンプレミス・ハイブリッドで データ主権 が必要なとき、プロトコル(OIDC + SAML)のカバレッジが広くなければならないとき、ライセンス費用なしで大規模にスケールするとき。マネージド SaaS(Auth0・Okta・Entra ID)との分かれ道は、たいてい「運用の負担を負うか、費用・依存を負うか」です — Keycloak は DB・アップグレード・可用性を自分で引き受ける代わりに、データとカスタマイズの完全な制御を与えてくれます。

考え直すべき点: アイデンティティサーバーは 単一障害点 です。落ちれば 20 個のアプリが同時にログイン不可になります。だからこそ、多重インスタンス + 外部セッション保存(Infinispan/DB)+ 無停止パッチは選択ではなく必須です。そして、トークン・セッション寿命、redirect URI のホワイトリスト、PKCE の強制といったセキュリティの基礎を落とせば、SSO はむしろ攻撃面を一か所に集めてしまうことになります。この感覚は認証・セキュリティ実習ラボで OAuth・OIDC・JWT を自分の手で動かしながら固めることをおすすめします。

おわりに

Keycloak は結局のところ「ログインを一か所に集める」インフラです。Realm(隔離)・Client(アプリ)・Role/Group(権限)・IdP(外部連携)の 4 概念で骨組みを立て、Authorization Code + PKCE でフローを理解し、build/start 2 段階 + hostname v2 でデプロイの落とし穴を避け、Organizations でマルチテナンシーを解けば — 20 個のアプリのログインが 1 つのよく守られた扉へ収束します。オープンソースでありながら標準を正直に踏襲している点こそ、10 年以上このプロジェクトが愛される理由です。