LabHub

ブログ

Keycloakで SSO を構築する — Realm・Client・フローから 2026 年の新機能まで

2026-07-09 · 14 分で読めます · #keycloak#sso#oidc#security#devops#authentication

한국어English日本語中文

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

社内アプリが 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)  「別の王国のパスポートを承認」

第 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 つ。

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

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

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

トークン交換(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 年以上このプロジェクトが愛される理由です。

参考資料

原文を読む: https://www.youngju.dev/blog/2026-07-09-keycloak-sso-guide.ja

コメント

まだコメントはありません。

ログインするとコメントできます