KeycloakとSpring BootのOAuth2連携ガイド

2026年7月2日

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

スポンサードリンク

KeycloakとSpring Boot連携の概要

Keycloakは、オープンソースで利用できる認証・認可プラットフォームであり、OAuth 2.0およびOpenID Connect (OIDC) を基盤にしたセキュアなユーザー管理を提供します。Spring Bootアプリケーションと統合することで、外部の認証サービスに依存せず、柔軟で拡張性のあるセキュリティ設計が可能です。

本記事では、最新のOIDC導入手順と過去のKeycloak Spring Bootアダプタ（非推奨）との比較を軸に、実装手順や注意点を解説します。特に、RBAC（ロールベースアクセス制御）やJWTトークンの活用法など、現行技術のベストプラクティスを押さえましょう。

KeycloakでのOIDC設定フロー

KeycloakとSpring Bootアプリケーションを連携するには、まずKeycloak側でクライアント登録と認証フロー構成を行う必要があります。

クライアント登録手順

Keycloak管理コンソールにアクセスし、「Clients」セクションを開く
新規クライアントを追加し、以下を設定：
Client ID: Spring Bootアプリケーションで使用する識別子（例: spring-boot-app）
Client Secret: 管理コンソール内で生成されたシークレットを取得
Redirect URIs: Spring Bootアプリケーションの認証コールバックURLを指定（例: http://localhost:8080/login/oauth2/code/keycloak）

認証フロー構成

Keycloakで利用するOIDCフローは、以下のように設定します：

Flow:「Client Credentials」または「Authorization Code」を選択
クライアント認証に使用するフローを明確に指定
Access Type:「Confidential」（シークレットが必要なケース）や「Public」（公開アプリケーション向け）を設定

Keycloakの公式ドキュメントでは、セキュリティリスクを最小限にするため、Confidential型が推奨されています。

Spring Securityとの統合方法

Spring Boot 2.x以降では、Spring Security OAuth2 ClientモジュールがKeycloak連携に最適です。

OAuth2 Client設定

application.ymlまたはapplication.propertiesで以下の設定を追加します：

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: spring-boot-app
            client-secret: {取得したシークレット}
            scope: openid, profile, email
            redirect-uri: &quot;{baseUrl}/login/oauth2/code/keycloak&quot;
            provider:
              keycloak:
                issuer-uri: https://keycloak-server.com/auth/realms/{リアルム名}

spring:

security:

oauth2:

client:

registration:

keycloak:

client-id: spring-boot-app

client-secret: {取得したシークレット}

scope: openid, profile, email

redirect-uri: "{baseUrl}/login/oauth2/code/keycloak"

provider:

keycloak:

issuer-uri: https://keycloak-server.com/auth/realms/{リアルム名}

{baseUrl}の置換ロジック: Spring Bootは起動時にアプリケーションのベースURLを自動で挿入します。手動での置換は不要です。

SecurityConfigの実装例

Spring Securityの設定クラスで、認証フローを定義します：

@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -&gt; auth
                .requestMatchers(&quot;/public/**&quot;).permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -&gt; oauth2
                .loginPage(&quot;/login&quot;)
                .defaultSuccessUrl(&quot;/&quot;)
            )
            .build();
    }
}

@EnableWebSecurity

public class SecurityConfig {

@Bean

public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {

return http

.authorizeHttpRequests(auth -> auth

.requestMatchers("/public/**").permitAll()

.anyRequest().authenticated()

)

.oauth2Login(oauth2 -> oauth2

.loginPage("/login")

.defaultSuccessUrl("/")

)

.build();

}

Client ID/Secret生成手順

セキュアなシークレット管理は、アプリケーションの安全性に直結します。

セキュアな秘密鍵管理方法

環境変数やSecret Manager（AWS Secrets Manager、HashiCorp Vaultなど）で保存
本番環境ではハードコーディングを絶対に避ける
Keycloakのトークンライフタイムとセキュリティ設定を同期させる

Keycloak管理コンソールでの操作

「Clients」 > 対象クライアントを選択
「Credentials」タブを開き、「Client Secret」を生成
生成されたシークレットは、アプリケーション設定ファイルに反映

RBACとJWTトークン活用法

Keycloakのロール情報をSpring Bootで利用するには、JWTペイロードからロール情報を抽出し、セキュリティ制御に組み込みます。

ロールベース認証の実装

Keycloak側でユーザーにロール（Role）を割り当て
Spring Securityでロール情報を取得する処理を追加：

public class KeycloakAuthenticationFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
        throws ServletException, IOException {
        String token = extractToken(request);
        if (token != null &amp;&amp; validateToken(token)) {
            Map&lt;String, Object&gt; claims = parseJwtClaims(token);
            List&lt;String&gt; roles = (List&lt;String&gt;) claims.get(&quot;realm_access&quot;);
            Authentication auth = new UsernamePasswordAuthenticationToken(
                request.getUserPrincipal(), 
                null, 
                getAuthorities(roles)
            );
            SecurityContextHolder.getContext().setAuthentication(auth);
        }
        filterChain.doFilter(request, response);
    }

    private List&lt;SimpleGrantedAuthority&gt; getAuthorities(List&lt;String&gt; roles) {
        return roles.stream()
            .map(SimpleGrantedAuthority::new)
            .collect(Collectors.toList());
    }
}

public class KeycloakAuthenticationFilter extends OncePerRequestFilter {

@Override

protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)

throws ServletException, IOException {

String token = extractToken(request);

if (token != null && validateToken(token)) {

Map<String, Object> claims = parseJwtClaims(token);

List<String> roles = (List<String>) claims.get("realm_access");

Authentication auth = new UsernamePasswordAuthenticationToken(

request.getUserPrincipal(),

null,

getAuthorities(roles)

);

SecurityContextHolder.getContext().setAuthentication(auth);

}

filterChain.doFilter(request, response);

}

private List<SimpleGrantedAuthority> getAuthorities(List<String> roles) {

return roles.stream()

.map(SimpleGrantedAuthority::new)

.collect(Collectors.toList());

}

Spring Securityとの整合性: 上記の処理はSpring Security標準仕様に準拠していますが、OAuth2 Clientモジュールで提供されるOAuth2AuthorizedClientを使用する方法も検討可能です。

JWTペイロードの解析方法

Keycloakが発行するJWTには以下のような情報を含みます：

項目	内容	補足
sub（Subject）	ユーザーID	一意な識別子
roles	ロール名リスト（例: `["user", "admin"]`）	RBACで使用する
exp（Expiration Time）	トークンの有効期限（Unixタイムスタンプ）	有効期間管理に重要

Spring Securityでは、JWTペイロードから取得したロール情報をAuthenticationオブジェクトに組み込み、アクセス制御を実施します。

旧アダプタと最新導入法の比較

Keycloak Spring Boot Starter（公式アダプタ）は非推奨となっており、現在ではSpring Security OAuth2 Clientが主流です。

技術的差異と選定ポイント

項目	旧アダプタ（deprecated）	最新導入法（Spring Security + OIDC）
設定方法	独自設定ファイルでの構成が必要	Spring Securityの標準API利用可能
サポート状況	非推奨・更新停止	持続的なメンテナンスあり
実装複雑さ	複数ファイルを管理する必要あり	単一設定ファイルで統合可能

最新導入法では、Keycloakが提供するOpenID Connect Discovery機能を活用できるため、設定ミスのリスクも低減されます。

セキュリティ設定のベストプラクティス

セキュアなSpring Bootアプリケーションを構築するには、以下のポイントに注力することが重要です。

通信暗号化

HTTPSを常に有効化し、トークン通信を保護
KeycloakサーバーとSpring Bootアプリケーションの間でSSL/TLS証明書を有効活用

トークン有効期限管理

Keycloak側でAccess Tokenのライフタイム（例: 1時間）を設定
リフレッシュトークンも最大有効期間を制限し、セキュリティリスクを最小化

ロールベースアクセス制御

ロールごとにアクセス可能なAPIパスを明示的に定義
例: @PreAuthorize("hasRole('ADMIN')")などSpring Securityのアノテーション活用

@RestController
public class AdminController {
    @GetMapping(&quot;/admin/data&quot;)
    @PreAuthorize(&quot;hasRole('ADMIN')&quot;)
    public String getAdminData() {
        return &quot;Admin only data&quot;;
    }
}

@RestController

public class AdminController {

@GetMapping("/admin/data")

@PreAuthorize("hasRole('ADMIN')")

public String getAdminData() {

return "Admin only data";

}

まとめ

本記事では、KeycloakとSpring Bootの統合に関する以下のポイントを解説しました：

Keycloak OIDC設定フローと認証フロー構成
Spring Securityとの最新導入手順（OAuth2 Client利用）
セキュアなClient ID/Secret管理方法
RBAC実装例とJWTトークンの活用法
旧アダプタとの比較と技術的選定ポイント
ベストプラクティスとしてのセキュリティ設定

Keycloak導入時は、公式ドキュメントと最新の実装手順を常に参照し、非推奨技術に注意しながら進めることが重要です。

スポンサードリンク

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

-KeyCloak

comment コメントをキャンセル

: KeyCloak

Keycloak 24でカスタムOIDCクレームを作成・活用する方法

本稿では、Keycloak 24.x における OIDC の必須クレームとオプションクレームの違いを踏まえ、ユーザー属性からカスタムクレームを UI と REST API の両方で作成し、Client Scope で再利用するベストプラクティスを紹介します。さらに、Spring Boot と Quarkus でそのクレームを取得・活用する実装例と、Docker Compose 環境での検証方法も解説しています。

: KeyCloak

Keycloak OIDC Custom Claims Setup Guide for Java Developers

This guide explains how to set up custom claims in Keycloak OIDC for Java developers and DevOps engineers, covering Realm configuration to Spring Security implementation with code samples.

: KeyCloak

Keycloak Custom Claims Implementation Without Quarkus

Learn to implement Keycloak custom claims via Java-based OIDC integration without relying on Quarkus extensions.

: KeyCloak

Keycloak 26 と Spring Security 6 の統合ガイド – OIDC 認証を簡単実装

Keycloak 26 と Spring Security 6 を組み合わせ、PKCE 対応の OIDC 認証を Spring Boot アプリに導入する具体的手順とベストプラクティスを紹介します。

: KeyCloak

Keycloak 26.x のインストール・初期設定とベストプラクティス

Keycloak 26.x のインストールからレルム作成、クライアント設定、SAML/OIDC連携までをステップバイステップで紹介します。

Keycloak Docker Compose デプロイ: セキュリティと外部DBのベストプラクティス

KubernetesでEnvoyサイドカーを構築する実践ガイド