Keycloak SSO環境構築の基礎と準備

Keycloak SSO環境構築の基礎と準備

Keycloakを用いたSSO環境構築には、導入前の準備が不可欠です。特に公式ドキュメントとの整合性確認や必要なツールの選定が成功の鍵となります。最新バージョン（2025年7月時点では19.0.3）と互換性のある環境を整えることで、後々の運用負担を軽減できます。

必要なツールと前提条件

SSO構築に必要な主なツールとその役割は以下の通りです。

上記の構成では、JavaとデータベースのバージョンがKeycloakの動作保証範囲内であることが重要です。公式サイトやGitHubリポジトリで最新情報は常に確認してください。

管理コンソールでのレルムとユーザー設定

Keycloakの管理コンソールを用いたレルム作成とユーザー登録は、SSO環境構築の基礎です。ここでは実務でよく使用される手順とセキュリティポリシーの初期値について解説します。

レルム作成のステップ

レルムは、認証情報を管理する仮想な組織単位として機能します。以下の手順で作成してください。

1. 管理コンソール（https://<host>:8443/admin）にログイン
2. 『Realms』 > 『Create Realm』 を選択
3. レルム名を入力し、『Create』 をクリック

作成後のレルム設定では、暗号化アルゴリズム（例：PBKDF2）やトークン有効期限（デフォルトは5分）の変更が可能です。これらはセキュリティ強化に直接影響するため、必要に応じて調整してください。

ユーザーアカウント登録・ロール割当

ユーザーをレルムに追加し、適切なロール（Role）を割り当てることで、アクセス制御が可能になります。手順は以下の通りです。

1. 『Users』 > 『Create User』 をクリック
2. ユーザー名とメールアドレスを入力し、『Save』
3. 作成したユーザーを選択し、『Roles』 タブからロールを追加

ロールは「管理者」「一般ユーザ」などに分類され、アクセス制御ポリシー（Access Control Policy）と連携します。初期値のロール権限は最小限に設定することを推奨します。

クライアントアプリケーションとの連携設定

クライアントアプリケーションとKeycloakの連携を確立するには、Client Authenticationの有効化やリダイレクトURIの設定が不可欠です。これらの手順を誤ると認証エラーが発生します。

Client Authenticationの有効化手順

クライアントアプリケーションにKeycloakが信頼できるようにするには、以下の手順でClient Authenticationを有効化します。

1. 管理コンソールの『Clients』 > 『Create Client』
2. クライアントIDとシークレット（Client Secret）を生成
3. 『Access Type』 を「confidential」に設定し、『Save』

このステップで生成されたクライアントIDとシークレットは、アプリケーション側での認証に使用されます。厳重に管理することをお忘れなく。

Redirect URIの正しい設定方法

Redirect URIは、認証後にユーザーが戻るURLを指定します。誤った設定ではSSOフローが中断するため注意が必要です。

• 必須条件
• リダイレクトURIはアプリケーション側の実際のエンドポイントと完全一致すること
• サポートしているプロトコル（HTTP/HTTPS）を確認し、一致させる

例：https://app.example.com/callback

また、複数のリダイレクトURIを登録する場合は、『Root URL』 にアプリケーションベースURLを設定しておくと管理が楽です。

OpenID ConnectプロトコルによるSSOフロー構築

OpenID Connectは、OAuth 2.0に基づく認証プロトコルで、SSO環境の基盤技術です。ここではAuthorization Codeフローとトークンライフタイム設定に焦点を当てます。

Authorization Codeフローの概要

Authorization Codeフローは、最もセキュアかつ一般的な認証フローです。以下の手順で動作します。

1. ユーザーがアプリケーションにログインリクエストを送信
2. Keycloakにリダイレクトされ、ユーザー認証と承諾を得る
3. アプリケーションにコード（Code）が戻される
4. Keycloakからトークン（Access Token / ID Token）が取得されて認証完了

このフローでは「Client Authentication」が必須です。これにより、不正なアプリケーションからのアクセスを防ぎます。

トークンライフタイム設定の最適化

トークンの有効期間はセキュリティとユーザー体験のバランスに大きく影響します。

• Access Tokenのデフォルト: 5分
• ID Tokenのデフォルト: 同じく5分

これらを変更するには、『Realm Settings』 > „Tokens“ セクションで調整可能です。企業内では10分以内に設定し、セキュリティリスクを最小限にすることが推奨されます。

フェデレーション設定における実践例

フェデレーション（Federation）は、外部認証プロバイダー（Google、SAMLなど）とKeycloakの連携を指します。特に企業ではGoogle Cloudとの連携が一般的です。

Google Cloudとの連携手順

1. Google Cloud Console でOAuthクライアントIDを作成
2. Keycloak管理コンソールの『Identity Providers』 > „Create Identity Provider“ を選択
3. プロバイダータイプに「Google」を選択し、Client IDとClient Secretを入力
4. 『Save』 してテスト認証を実施

このとき注意点として、以下の情報を正しく設定する必要があります。

• クライアントID（Client ID）：Google Cloudプロジェクト内で取得したもの
• リダイレクトURI（Redirect URI）：https://your-keycloak-host/realms/your-realm-name/protocol/openid-connect/callback/google

セキュリティ強化と運用ベストプラクティス

Keycloakのセキュリティを高めるには、メタデータファイルの導入や証明書管理が不可欠です。以下に具体的な手順と注意点を紹介します。

メタデータファイルの導入手順

OpenID Connectプロトコルでは、認証情報を取得するために「メタデータファイル」が必要です。このファイルは以下のURLで参照できます。

このURLはクライアントアプリケーションが自動的に読み込むため、外部アクセス可能に設定する必要があります。

証明書の定期更新ポリシー

Keycloakでは、トークン署名に使用される証明書を管理できます。以下の手順で確認・更新しましょう。

1. 『Realm Settings』 > „Keys“ から証明書一覧を表示
2. 切替対象の証明書を選択し、『Rotate Key』 を実施
3. 更新後は、認証フローをテストして正常動作を確認

証明書の更新周期は6か月〜1年程度が一般的です。自動更新機能があれば、運用負担を軽減できます。