Contents
Keycloak OIDC設定でSpring Boot 3環境をセキュアに構築する意義
Keycloak OIDC設定は、Java開発者にとってSSO（シングルサインオン）の実装において不可欠な技術です。特にSpring Boot 3とSecurity 6の組み合わせでは、従来からある認証・認可フレームワークを現代的なセキュリティ基準に適合させることが求められます。OIDC（OpenID Connect）はOAuth 2.0に基づく標準プロトコルで、ユーザー情報の検証とセッション管理を提供します。この記事では、Keycloak OIDCクライアントの設定手順をステップバイステップで解説し、Spring Boot 3との統合方法も具体的に紹介します。
Keycloak管理者画面でのクライアント登録手順
Spring BootアプリケーションがKeycloakと連携するためには、まずKeycloakの管理コンソールでクライアントを登録する必要があります。このプロセスは後続の認証フローの基盤となる重要なステップです。
管理コンソールアクセス
Keycloakサーバーに接続し、管理者としてログインします。以下のような手順で操作を行います。
- KeycloakサーバーのURL（例：
http://localhost:8080/auth/admin/realms/realm-name）にアクセスします。 - ログイン後、クライアント（Clients）タブを選択し、新しいクライアントを追加します。
新規クライアント作成
以下の設定を行います。
- クライアントID：任意の名前を入力（例：
spring-boot-app）。このIDは後でSpring Bootアプリケーションに設定します。 - クライアントタイプ：公開クライアント（public） または 機密クライアント（confidential） を選択。Webアプリケーションでは通常「機密クライアント」を推奨します。
リダイレクトURI設定
Spring Bootアプリケーションの認証コールバック先URLを入力します。
- リダイレクトURI：
http://localhost:8080/login/oauth2/code/keycloakなどの形式で記載します。 - 複数のURIが必要な場合は、カンマで区切って記載します。
注意：リダイレクトURIはSpring Bootアプリケーションの実際のルートに一致させる必要があります。不一致の場合、認証フローが正しく動作しません。
PKCE認証フローの有効化と構成
PKCE（Proof Key for Code Exchange）は、公開クライアント向けのセキュリティ強化仕様で、OAuth 2.0のコードフローにおけるリスクを軽減します。特にWebフロントエンドアプリケーションでは必須となる技術です。
PKCEオプションの確認
Keycloak管理コンソールのクライアント設定ページへ移動し、以下を行います。
- OAuth 2.0 タブを開き、PKCE（Proof Key for Code Exchange） チェックボックスをONにします。
- フロー種類として
Authorization Code with PKCEを選択します。
クライアントセキュリティ設定変更
以下のように設定します。
| 項目 | 値 | 補足 |
|---|---|---|
| フロー種類 | Authorization Code with PKCE |
クライアントシークレット不要、セキュリティ高めの選択肢 |
| PKCE有効化 | ON | 任意の公開クライアントに適用可能 |
重要ポイント：PKCEはOAuth 2.0コードフローにおいてリプレイ攻撃を防ぐために設計されており、特にフロントエンドアプリケーションで必須です。
Client ID/Secretの生成と管理方法
KeycloakではクライアントIDとシークレットが自動生成されるため、開発者はそれをSpring Bootアプリに適切に導入する必要があります。シークレットの安全な管理はセキュリティ設計の根幹です。
クライアントシークレット生成
Keycloak管理コンソールのクライアント設定ページで以下の手順を実行します。
- クライアントシークレット（Client Secret）フィールドに「Generate」をクリックし、自動生成された文字列を取得します。
- シークレットはセキュリティ管理ツールを使用して保存・管理することを推奨します。
環境ごとのセキュリティ対策
以下のように環境に応じた設定を行います。
-
開発環境：シークレットは
application.propertiesや環境変数で管理。例：
properties
spring.security.oauth2.client.registration.keycloak.client-secret=your-generated-secret -
本番環境：Secret Managementツール（HashiCorp Vault、AWS Secrets Manager、Azure Key Vaultなど）を使用し、コードに直接シークレットを埋め込まない。
セキュリティの注意点：クライアントシークレットは絶対に公開しないようにしてください。Gitレポジトリやログに記録しないことが重要です。
OIDC認証フロー選定の考え方
OIDCにはいくつかの認証フローがありますが、セキュリティを重視する場合はAuthorization Code with PKCEが最適です。特にSpring Security 6ではこのフローとの互換性が高く、現代的な開発に合致します。
フロー種類比較
以下はOIDC認証フローの特徴と使用シーンを比較した表です。
| フロー | セキュリティ | 使用シーン | Spring Boot対応 |
|---|---|---|---|
| Authorization Code with PKCE | 高 | Webフロントエンド、モバイルアプリなど公開クライアント | ✅ Spring Security 6 対応 |
| Implicit Flow | 中 | 単純なリダイレクトが必要なケース（非推奨） | ❌ Spring Security 6 不対応 |
| Hybrid Flow | 高 | クライアントシークレットが必要なシナリオ | ✅ Spring Security 6 対応 |
Spring Security 6対応設定
Spring Boot 3ではSecurity 6が採用され、OIDCフローのサポートが強化されています。以下の依存関係をbuild.gradleまたはpom.xmlに追加してください。
|
1 2 3 |
implementation 'org.springframework.boot:spring-boot-starter-security' implementation 'org.springframework.security:spring-security-oauth2-client' |
Spring Boot 3でのKeycloak統合サンプルコード
ここでは、Spring Boot 3とSecurity 6を使用したKeycloakの統合方法をステップバイステップで解説します。
依存関係設定
build.gradle.ktsに以下を追加：
|
1 2 3 4 5 |
dependencies { implementation("org.springframework.boot:spring-boot-starter-security") implementation("org.springframework.security:spring-security-oauth2-client") } |
セキュリティ構成クラス（SecurityFilterChainを使用）
SecurityConfig.ktを作成し、Keycloakとの統合を設定します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
@Configuration @EnableWebSecurity class SecurityConfig { @Bean fun securityFilterChain(http: HttpSecurity): SecurityFilterChain { return http .authorizeRequests { authz -> authz .antMatchers("/public/**").permitAll() .anyRequest().authenticated() } .oauth2Login { } .oidcResourceServer { withIdTokenIntrospection() } .build() } } |
認証成功時の処理（OAuth2SuccessHandlerのカスタマイズ）
認証が成功した場合、ユーザー情報をセッションに保存します。OAuth2SuccessHandlerをカスタマイズすることで、任意のロジックを追加できます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
class CustomOAuth2SuccessHandler : AuthenticationSuccessHandler { override fun onAuthenticationSuccess( request: HttpServletRequest, response: HttpServletResponse, authentication: Authentication ) { val user = authentication.principal as? OAuth2User ?: return // カスタム処理（例：ユーザー情報をロギング） println("認証成功: ${user.name}") // リダイレクトなど実装可能 response.sendRedirect("/") } } |
まとめ
Keycloak OIDC設定を通じたSpring Boot 3環境構築は、現代的なSSO実装に不可欠です。クライアント登録からPKCE有効化、シークレット管理までを丁寧に理解することで、セキュリティリスクが大幅に低減されます。また、Spring Security 6との組み合わせにより、より信頼性の高い認証フローを構築可能です。