KeycloakとOIDCをSpring Bootで導入する方法

KeycloakとOIDCの導入背景

Keycloakを用いたOIDCクライアントの実装は、企業や開発者にとってセキュリティの強化と運用効率の向上に直結する重要なテーマです。特にSpring Bootアプリケーションとの統合では、外部認証サービスを簡単に導入できるため、プロジェクトの初期設計段階から検討されるケースが増加しています。

セキュリティ強化の観点からは、Keycloakが提供するOIDCプロトコルは、OAuth 2.0ベースの認可フローと組み合わせて、アプリケーションに安全なログインおよびアクセス制御を実装できる点で優れています。また、ユーザー認証とAPI保護の分離によって、開発効率と保守性が同時に向上するため、中規模以上のシステム構築には欠かせない技術です。

以下では、Keycloakサーバーの初期設定からSpring Bootアプリケーションへの実装まで、具体的な手順をステップバイステップで解説します。本記事に沿って実際にKeycloakを導入し、OIDC認証フローを構築してみてください。

Keycloakサーバーの初期設定手順

Keycloakサーバーの初期設定は、後続のOIDCクライアント作成やSpring Bootとの連携に不可欠です。現在最新バージョン（2023年時点）ではDockerで起動する方法が推奨されており、簡単に環境を構築できます。

DockerでのKeycloakサーバー起動

KeycloakのDockerイメージは公式リポジトリから取得可能です。以下の手順で実行します。

1. Dockerイメージをpull
   bash
docker pull quay.io/keycloak/keycloak:latest

2. コンテナを起動（環境変数で初期アカウント設定）
   bash
docker run -d --name keycloak -p 8080:8080 \
-e KEYCLOAK_USER=admin \
-e KEYCLOAK_PASSWORD=AdminPass123 \
quay.io/keycloak/keycloak:latest

注意：KEYCLOAK_PASSWORDはセキュリティの観点から、適切な強度のパスワードを設定してください。

管理者アカウントの作成

Docker起動後、ブラウザで http://localhost:8080 にアクセスするとKeycloak管理画面が表示されます。管理者アカウントは上記の環境変数で指定したもの（例：admin / AdminPass123）を使用します。

ベーステーマのカスタマイズ

Spring BootアプリケーションとのUI統合を円滑にするため、Keycloakのベーステーマをカスタマイズすることも可能です。

• カスタムCSSやJavaScriptの追加
  管理画面 → Themes → Import theme から、公式テーマをインポートまたは独自テーマをアップロードします。

OIDCクライアントの作成と設定

KeycloakではOIDCクライアントを作成し、Spring Bootアプリケーションに接続させる必要があります。以下は必要最低限の手順です。

Client ID/Secretの生成フロー

1. Keycloak管理画面 → Realm → Clients を選択
2. [Create] ボタンをクリックし、クライアント名（例：spring-oidc-client）を入力
3. Client Type は openid-connect を選択
4. Root URL にアプリケーションのURLを設定（例：http://localhost:8081）

重要：クライアントシークレットは管理画面で生成し、Spring Boot側での設定に反映する必要があります。

Redirect URIの有効範囲指定

Redirect URIは、OAuth2フローで認証完了後のリダイレクト先となるため、正しく設定しなければなりません。

• 例：http://localhost:8081/login/oauth2/code/keycloak

重要：Spring Bootアプリケーションの実際のURLに合わせて設定してください。

Access Typeの選択ロジック

Spring Bootアプリケーションでは confidential を選択し、Client Secretを取得する必要があります。

認可フローの選定と実装

OIDC認証には「コード・トークンフロー」といったいくつかのオプションがありますが、Spring Bootとの連携に最適なフローを選びましょう。

コード・トークンフローの比較

注意：OAuth 2.1仕様では、Implicitフローは廃止されているため、Spring BootアプリケーションではAuthorization Codeフローが必須です。

Spring Securityでのフロー統合

Spring Boot 3.xでは、spring-security-oauth2-resource-serverモジュールを使用してOIDCを実装します。基本的な設定手順は以下の通りです：

1. build.gradleに依存関係を追加
   groovy
implementation 'org.springframework.security:spring-security-oauth2-resourceserver:6.0.3'

2. application.ymlでKeycloak設定を記述
   yaml
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: http://localhost:8080/realms/myrealm
jwk-set-uri: ${spring.security.oauth2.resourceserver.jwt.issuer-uri}/protocol/openid-connect/certs

Spring Bootへのライブラリ導入と設定

Spring BootアプリケーションにKeycloakを統合するには、正しいライブラリと設定ファイルの記述が不可欠です。

必要なライブラリとその役割

注意：Spring Boot 3.xではOAuth2Clientモジュールも必要です。

application.ymlでのKeycloak設定項目

以下はSpring Boot 3.xで動作するKeycloakとの統合に必要なYAML設定例です。

重要：client-secretはKeycloak管理画面で取得した値を入力してください。

トークン検証ロジックの実装とカスタムクレーム

Keycloakから取得したアクセストークンを適切に検証し、必要に応じて自定义クレームを処理します。

JWTの署名検証処理

Spring SecurityはデフォルトでJWTの署名検証を行い、トークンが無効な場合は401 Unauthorizedを返却します。ただし、カスタム検証ロジックが必要な場合は以下のように拡張できます。

自定义クレームの型定義

Keycloakでカスタムクレームを設定し、Spring Bootアプリケーションで受け取るには以下のように実装します。

セキュリティポリシーの動的反映

トークン内のクレーム情報をもとに、権限チェックやアクセス制御を動的に変更可能です。

• 例：ロールごとのアクセス制限
  java
@PreAuthorize("hasAuthority('ROLE_ADMIN')")
public ResponseEntity<String> adminOnlyResource() {
return ResponseEntity.ok("Admin only");
}

まとめ

本記事では、Keycloakを用いたOIDCクライアントの実装フローについて、Spring Bootアプリケーションとの統合例中心に解説しました。以下の重要なポイントを確認してください。

• KeycloakサーバーはDockerで簡単に起動可能
• OIDCクライアント作成時にClient ID/SecretとRedirect URIの設定が不可欠
• Spring BootアプリケーションではAuthorization Codeフローが推奨される
• spring-security-oauth2-resource-serverモジュールを使用してトークン検証を実装する

今後は、KeycloakとSpring Bootの連携に加え、他の認証プロトコル（SAMLなど）との統合も検討する価値があります。本記事に沿って実際にKeycloakを導入し、OIDC認証フローを構築してみてください。