Contents
Keycloakサーバーのインストールと基本設定
KeycloakサーバーはDockerで簡単に導入可能ですが、バージョン管理に注意が必要です。以下に安定したバージョンでの起動手順を示します。
Dockerでの起動手順
Keycloakは公式イメージを使用して素早く導入可能です。以下のコマンドでコンテナを立ち上げます。バージョンを固定するため、latestではなく特定のバージョン（例: 20.0.6）を指定します。
|
1 2 |
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=secret quay.io/keycloak/keycloak:20.0.6 |
実行後、ブラウザで http://localhost:8080/auth にアクセスし、管理者アカウントを作成してください。
管理者アカウントの作成
Keycloak管理画面にログイン後、以下の手順で管理者アカウントを設定します。
- 「Add User」ボタンをクリック
- ユーザーID（例:
admin）とパスワードを入力 - 「View Password」オプションを有効化し、認証方法を指定
管理者アカウントはクライアントアプリケーションの設定に必要です。
クライアントアプリケーションの登録
Spring BootアプリケーションをKeycloakと連携させるには、クライアントとして登録が必要です。
- 「Clients」タブ → 「Create」
- 実装するSpring Bootアプリケーション名（例:
springboot-app）を指定 - Client ID は自動生成されるため、変更不要
- Access Type を confidential に設定し、Valid Redirect URIs に
http://localhost:8080/*を入力
登録後、「Credentials」タブからクライアントシークレットを取得してください。このシークレットは後ほどapplication.propertiesに記述します。
Spring Bootプロジェクトへの依存関係追加
Spring Bootアプリケーションには、Spring SecurityとKeycloak Spring Boot Starterの2つのライブラリが必要です。
Spring Securityの導入
Spring Securityは認証・認可を実現するための核となるフレームワークです。以下にbuild.gradleやpom.xmlへの記述例を示します。
Gradle（build.gradle）
|
1 2 3 4 |
dependencies { implementation 'org.springframework.boot:spring-boot-starter-security' } |
Maven（pom.xml）
|
1 2 3 4 5 |
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency> |
Spring Securityを導入することで、リソースへのアクセス制限やセッション管理が可能になります。
Keycloak Spring Boot Starterの設定
Keycloakとの連携には専用ライブラリが必要です。以下に追加方法を示します。
注意: Keycloak Spring Boot Starterのバージョンは、Keycloakサーバーのバージョンと互換性を持たせる必要があります。以下の表を参考にしてください。
|
1 2 3 4 5 |
| Keycloakバージョン | Spring Boot Starterバージョン | |--------------------|-------------------------------| | 20.x | 18.0.0 | | 19.x | 17.0.0 | |
OAuth2/OIDC認証フローの構築
OAuth2/OIDCを用いた認証フローでは、セキュアなエンドポイントとトークンベースの認可処理を実装します。
セキュアなエンドポイントの作成
以下の手順で保護されたリソースを作成します。
@RestControllerアノテーションを付与したクラスを作成hasRole('USER')のロールマッピングについて: Keycloakに登録したユーザーのロール（例:user）は、Spring Securityで自動的にROLE_userとして扱われます。そのため、@PreAuthorize("hasRole('USER')")はKeycloakのロール名と一致させる必要があります。
|
1 2 3 4 5 6 7 8 |
@RestController public class SecureResourceController { @GetMapping("/secure") public String getSecureData() { return "This is a secure endpoint."; } } |
このエンドポイントには、Keycloak経由で認証されたユーザーのみがアクセスできます。
トークンベースの認可処理
Spring SecurityはOAuth2トークンを自動解析して認証情報を取得します。以下に基本的な設定例を示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
@Configuration @EnableWebSecurity public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter { @Override protected void configure(HttpSecurity http) throws Exception { super.configure(http); http.authorizeRequests() .antMatchers("/secure/**").authenticated(); } } |
この設定により、/secure/**以下のパスにアクセスする際には、Keycloakによる認証が強制されます。
application.propertiesの記述例
Spring Bootアプリケーションでは、Keycloakサーバーへの接続情報をapplication.propertiesファイルに記述します。
Keycloakサーバー接続設定
以下のように、KeycloakサーバーのURLとリールムを指定します。リールム名は具体的な例（例: springboot-realm）を記載してください。
|
1 2 3 4 |
keycloak.realm=springboot-realm keycloak.auth-server-url=http://localhost:8080/auth keycloak.ssl-required=external |
クライアントID・シークレットの指定
前項で登録したクライアントアプリケーション情報を以下に記述します。
|
1 2 3 |
keycloak.client-id=springboot-app keycloak.credentials.secret=your-client-secret |
注意: your-client-secretは、Keycloak管理画面から取得したクライアントシークレットを入力してください。
認証失敗時のカスタムハンドリング
Keycloakとの認証が失敗した場合に、エラーレスポンスのカスタマイズやロギング処理を行う方法です。
エラーレスポンスのカスタマイズ
認証失敗時のレスポンスをカスタマイズするには、OAuth2ExceptionTranslatorを実装します。以下に、基本的な例外処理例と拡張例を示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
public class CustomOAuth2ExceptionTranslator implements OAuth2ExceptionTranslator { @Override public ResponseEntity<OAuth2Error> translate(Exception ex) { if (ex instanceof InvalidTokenException) { return new ResponseEntity<>(new OAuth2Error("INVALID_TOKEN", "トークンが無効です", null), HttpStatus.BAD_REQUEST); } else if (ex instanceof UnauthorizedException) { return new ResponseEntity<>(new OAuth2Error("UNAUTHORIZED", "認証に失敗しました", null), HttpStatus.UNAUTHORIZED); } // その他の例外処理 return new ResponseEntity<>(new OAuth2Error("UNKNOWN_ERROR", "予期せぬエラーが発生しました", null), HttpStatus.INTERNAL_SERVER_ERROR); } } |
このようにして、ユーザーが理解しやすいエラーメッセージを返却できます。
ロギング処理の実装
認証失敗時の状況を把握するためには、ロギング処理を実装するのが有効です。
|
1 2 3 4 5 6 7 8 9 10 |
public class CustomAuthenticationFailureHandler implements AuthenticationFailureHandler { @Override public void onAuthenticationFailure(HttpServletRequest request, HttpServletResponse response, AuthenticationException exception) throws IOException, ServletException { // ログ出力とカスタムレスポンスの返却 logger.error("認証失敗: {}", exception.getMessage()); response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "ログインに失敗しました"); } } |
この処理により、セキュリティ上の問題を迅速に切り分けられるようになります。
まとめ
本記事では、KeycloakとSpring Bootの統合手順をステップバイステップで解説しました。重要なポイントを以下に整理します：
- KeycloakサーバーはDockerでの導入が推奨され、バージョン固定が必要
- Spring SecurityとKeycloak Starterを使用することで認証フローが構築可能
application.propertiesにはリールム名やクライアントシークレットを明示的に記述- 認証失敗時の処理はカスタマイズし、セキュリティの強化を図る
記事内のサンプルコードを参考に、すぐにKeycloakとSpring Bootの統合を試してみましょう。