Contents
KeycloakとSpring Bootの連携によるセキュアアプリ構築の概要
Keycloakを活用した認証・認可は、現代のWebアプリケーション開発において不可欠な技術です。OIDC（OpenID Connect）との統合により、標準化された認証フローとセキュリティの強化が可能になります。本記事では、2023年時点での最新情報を基に、Spring BootアプリケーションにおけるKeycloak連携を具体的なコード例とともに解説します。実務導入時の参考となる情報を提供し、信頼性のあるセキュアなWebアプリ構築を目指します。
Keycloakサーバーのインストールと初期設定
KeycloakはSpring Bootとの連携に不可欠な認証プロバイダーです。公式Dockerイメージを用いることで手軽に環境構築が可能です。管理者アカウントやRealmの作成など、開発フローにおける重要な初期ステップについて解説します。
Dockerを使用したKeycloakの起動手順
以下にKeycloakのDockerでの起動手順を示します。
-
Dockerイメージの取得
bash
docker pull quay.io/keycloak/keycloak:latest -
コンテナの起動
bash
docker run -d --name keycloak \
-p 8080:8080 \
-e KEYCLOAK_ADMIN=admin \
-e KEYCLOAK_ADMIN_PASSWORD=admin \
quay.io/keycloak/keycloak:latest -
ブラウザでアクセス
http://localhost:8080 を開き、Keycloakの管理画面にログインします。
注意: ポート
8080はKeycloakのデフォルトですが、既存のサービスと競合する可能性があります。必要に応じて-p 8081:8080のように変更してください。
管理者アカウントの作成とRealm設定
管理者アカウントはKeycloakの初期設定で必須です。また、Realm（ドメイン）をアプリケーションごとに分離管理することで、セキュリティと運用効率が向上します。
- 管理者アカウントの作成
-
管理画面から「Add Realm」を選択し、「myrealm」といった名前で新規Realmを作成します。
-
クライアントの準備
-
「Clients」セクションからクライアントを作成し、アプリケーションとの連携用にクライアントIDとシークレットを取得します。
-
役割の設定（オプション）
- 「Roles」セクションでユーザーに割り当てるロールを定義しておくと、RBAC実装時に便利です。
Spring BootアプリケーションへのKeycloakクライアント登録
Spring Bootプロジェクトでは、Keycloakとの連携のためにクライアント情報を設定します。この手順は、アプリケーションがKeycloakサーバーにアクセスできるようにするために不可欠です。
Keycloak管理者画面でのクライアント作成手順
-
管理画面にアクセス
http://localhost:8080/admin へログインし、「Clients」セクションを開きます。 -
新規クライアントの作成
-
「Create」ボタンをクリックし、クライアントID（例：
springboot-app）とシークレットを生成します。 -
Redirect URIの設定
-
クライアントにアクセスするアプリケーションのURL（例：
http://localhost:8081/realms/myrealm/protocol/openid-connect/auth）を指定します。 -
スコープの選択
- 必要なスコープ（OpenID、profileなど）を選択し、保存します。
注意: Redirect URIにWildcard（
*）を付けると、サブパスも許可されますが、リダイレクト攻撃のリスクがあります。信頼できるドメインのみ指定してください。
application.propertiesでの認証設定ファイル構成
Spring BootアプリケーションでKeycloakを有効化するために、application.propertiesにOIDCプロバイダー情報を記述します。
OIDCプロバイダーコンフィギュレーション
以下は、Keycloak認証設定の基本例です：
|
1 2 3 4 5 6 |
spring.security.oauth2.client.registration.keycloak.client-id=springboot-app spring.security.oauth2.client.registration.keycloak.client-secret=your-client-secret spring.security.oauth2.client.registration.keycloak.authorization-grant-type=authorization_code spring.security.oauth2.client.registration.keycloak.redirect-uri=http://localhost:8081/* spring.security.oauth2.client.provider.keycloak.issuer-uri=https://localhost:8080/realms/myrealm |
ポイント:
client-secretはKeycloakから取得したものを必ず使用し、アプリケーション外で安全に管理してください。
Spring Security設定の改善とコード例
Spring Boot 3.x以降では、WebSecurityConfigurerAdapterは非推奨となっています。代わりにSecurityFilterChainを直接定義する方法が推奨されます。
セキュリティ設定のサンプルコード（Spring Boot 3.x対応）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
@EnableWebSecurity public class SecurityConfig { @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { return http .authorizeHttpRequests(auth -> auth.anyRequest().authenticated()) .oauth2Login() .defaultSuccessUrl("/") .and() .build(); } } |
注意: すべてのリクエストを認証する設定は、開発環境でのみ使用してください。実運用では必要なエンドポイントのみ認証します。
RBAC（Role-Based Access Control）の実装方法
RBACにより、ユーザーが持つ役割に基づいてアクセスを制限できます。Keycloakで定義したロールをSpring Securityとマッピングする手順を説明します。
KeycloakロールとSpring Securityのマッピング
以下は、Role-Based Access Controlの実装例です：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
@Configuration @EnableWebSecurity public class SecurityConfig { @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { return http .authorizeHttpRequests(auth -> auth .antMatchers("/admin/**").hasRole("ADMIN") .antMatchers("/user/**").hasRole("USER")) .oauth2ResourceServer().jwt() .and().build(); } } |
ポイント:
hasRole("ADMIN")は、Keycloakで定義した「admin」ロールを参照します。
JWTトークンによるAPIセキュリティの具体例
JWT（JSON Web Token）は、信頼性のある認証手段として広く利用されています。Spring Bootアプリケーションでは、JWTトークンを用いたアクセス制限が可能です。
トークン検証ロジックの実装
Keycloakから取得したトークンを検証するためには、JwtAuthenticationConverterクラスを使用します。以下に設定例を示します：
|
1 2 3 4 5 6 7 8 9 10 11 |
@Bean public JwtDecoder jwtDecoder() { return NimbusJwtDecoder.withIssuerLocation("https://localhost:8080/realms/myrealm") .build(); } @Bean public OAuth2ResourceServerConfigurer<HttpSecurity> resourceServer(OAuth2ResourceServerProperties properties) { return new OAuth2ResourceServerConfigurer<>(properties); } |
クライアントシークレットとトークンの管理ベストプラクティス
セキュリティの観点から、以下のような管理方法が推奨されます：
- クライアントシークレット:
- 環境変数やSecrets Manager（AWS Secrets Managerなど）に保存し、コード内に硬编码しない。
-
テスト環境では
@TestPropertySourceで別途設定ファイルを読み込む。 -
トークンの管理:
- クライアントシークレットは短期間で有効期限が切れるように設定する（Keycloakで設定可能）。
- JWTトークンはHTTPヘッダーに
Authorization: Bearer <token>形式で送信し、HTTPSによる暗号化を必ず行う。
リダイレクトURIのセキュリティリスクと回避策
リダイレクトURIにWildcard（*）を使用すると、任意のサブパスが許可されるため、以下のリスクがあります：
| リスク | 説明 |
|---|---|
| リダイレクト攻撃 | 恶意のあるURLにリダイレクトされる可能性がある。 |
| 信頼性の低下 | 不正なサブパスが許可され、アプリケーションに影響を与える可能性がある。 |
回避策:
- リダイレクトURIは具体的なURL（例：
http://localhost:8081/callback）を指定し、Wildcard使用を控える。 - Keycloak側で「Valid Redirect URIs」の設定を厳密に管理する。
まとめ
本記事では、2023年時点での最新情報に基づき、KeycloakとSpring Bootを連携させるための手順をご説明しました。具体的には以下の点を解説しました：
- Keycloakサーバーのインストールと初期設定方法
- Spring Bootアプリケーションでのクライアント登録手順
application.propertiesの認証設定ファイル構成例- RBACによるアクセス制限の実装方法
- JWTトークンを使用したAPIセキュリティの具体例
Keycloakを活用することで、セキュアなWebアプリケーション構築が可能になります。本記事の手順に従って、自分のプロジェクトでも導入試行してみてください。