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

2026年6月24日

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

スポンサードリンク

働き方から選べる

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

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

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

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

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

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

Beyond Careerに無料相談する

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

Contents

1 Keycloak 26.0（Red Hat ビルド）の新機能と OIDC 標準サポート
- 1.1 主な変更点の概要
2 OpenID Connect と PKCE の統合的な解説
- 2.1 OIDC の基本フローモデル（概要）
- 2.2 PKCE（Proof Key for Code Exchange）とは
3 Realm とクライアントの基本概念
- 3.1 Realm の概要（導入文）
- 3.2 Client の概要（導入文）
4 Spring Boot 3.x と Spring Security 6 の基本構成
- 4.1 プロジェクト雛形の作り方（導入文）
- 4.2 依存関係とバージョン管理（導入文）
5 Keycloak 側の Realm／Client 作成と Spring 設定
- 5.1 Realm と Client の作成手順（導入文）
- 5.2 Spring 側設定例（導入文）
6 OIDC 認証フローとトークン検証の実装
- 6.1 認可コードフロー＋PKCE の構成（導入文）
- 6.2 アクセストークン・IDトークンの自動検証とカスタム Claim マッピング（導入文）
7 ロール／権限マッピングと API 保護
- 7.1 Role → GrantedAuthority の変換ロジック（導入文）
- 7.2 @PreAuthorize でエンドポイントを保護する例（導入文）
8 デプロイ・運用、マイグレーション、トラブルシューティング
9 まとめ

スポンサードリンク

Keycloak 26.0（Red Hat ビルド）の新機能と OIDC 標準サポート

Keycloak 26.0 は OpenID Connect の標準フローをそのまま利用できるよう大幅に改善されています。PKCE がデフォルトで有効になるほか、RP‑initiated ログアウトやセッション同期エンドポイントが新たに追加され、Spring Security 6 とのシームレスな連携が可能です。本節では主な機能と導入メリットを概観します。

主な変更点の概要

PKCE が自動的に有効化（設定不要でコードインジェクションリスク低減）
RP‑initiated ログアウト API の提供により、シングルサインアウトが容易に実装可能
セッション同期エンドポイント で外部アプリケーションと認証状態を共有できる

OpenID Connect と PKCE の統合的な解説

この章では OIDC の全体像と、PKCE がどのように認可コードフローを保護するかをまとめて説明します。重複して記載されていた箇所を一つに統合し、読者が一目で理解できる構成にしています。

OIDC の基本フローモデル（概要）

OpenID Connect は OAuth 2.0 の認可コードフローをベースに ID トークンを付加したプロトコルです。クライアントは authorization‑code を取得し、トークンエンドポイントでアクセストークンと ID トークンを交換します。

PKCE（Proof Key for Code Exchange）とは

PKCE は認可コードフローに対する追加の検証手段です。クライアントはランダムな code verifier を生成し、ハッシュ化した code challenge を認可リクエストに付与します。トークン交換時に同じ verifier を送信することで、認可コードが第三者に盗まれても不正利用できないようにします。

利点
公開クライアント（SPA やモバイル）でも安全に認証可能
サーバーサイドでの client‑secret が不要になるケースが増える

Keycloak 26.0 では「Enable PKCE」オプションがデフォルトでオンになり、開発者は設定を意識せずにこの保護機構を利用できます。

Realm とクライアントの基本概念

Realm と Client の関係性を正しく把握することは、Keycloak を運用する上で最も重要です。本節ではそれぞれの役割と設定ポイントを簡潔に解説します。

Realm の概要（導入文）

Realm はユーザー・ロール・クライアントなどの認可情報を論理的に分離する単位です。開発環境と本番環境で別々の Realm を作成すれば、設定ミスやデータ漏洩リスクを低減できます。

主な要素
ユーザー管理（登録・パスワードポリシー）
ロール定義とロールマッピング
クライアント（外部アプリケーション）の登録

Client の概要（導入文）

Client は OIDC における client‑id と client‑secret を持ち、認可サーバーとのやり取りを行うエンティティです。Spring Boot アプリではリダイレクト URI を /login/oauth2/code/* に合わせる必要があります。

必須項目
Client ID（例：spring-boot-app）
Client Secret（confidential クライアントの場合必須）
Valid Redirect URIs（例：http://localhost:8080/login/oauth2/code/keycloak）

Spring Boot 3.x と Spring Security 6 の基本構成

Spring Boot 3 系は Java 17+ を前提にモジュール化が進み、Spring Security 6 は OAuth2/OIDC クライアント機能をコアに据えています。本節ではプロジェクトの雛形作成から依存関係管理までを網羅的に解説します。

プロジェクト雛形の作り方（導入文）

Spring Initializr で必要なスターターを選択し、ビルドツールと Java バージョンを指定すれば、認証連携に必要な土台が自動生成されます。

plugins {
    id(&quot;org.springframework.boot&quot;) version &quot;3.2.0&quot;
    kotlin(&quot;jvm&quot;) version &quot;1.9.0&quot;
}
java.sourceCompatibility = JavaVersion.VERSION_17

plugins {

id("org.springframework.boot") version "3.2.0"

kotlin("jvm") version "1.9.0"

}

java.sourceCompatibility = JavaVersion.VERSION_17

依存関係とバージョン管理（導入文）

Spring Boot の BOM (spring-boot-dependencies) を dependencyManagement にインポートすれば、個別のバージョン指定は不要です。これにより Keycloak Adapter 等旧来の依存関係を排除し、標準 OAuth2 フローだけで完結できます。

&lt;dependencyManagement&gt;
    &lt;dependencies&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
            &lt;artifactId&gt;spring-boot-dependencies&lt;/artifactId&gt;
            &lt;version&gt;${spring-boot.version}&lt;/version&gt;
            &lt;type&gt;pom&lt;/type&gt;
            &lt;scope&gt;import&lt;/scope&gt;
        &lt;/dependency&gt;
    &lt;/dependencies&gt;
&lt;/dependencyManagement&gt;

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-dependencies</artifactId>

<version>${spring-boot.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

Keycloak 側の Realm／Client 作成と Spring 設定

Keycloak 管理コンソールで行う設定手順と、Spring アプリ側に必要な application.yml の記述例を具体的に示します。

Realm と Client の作成手順（導入文）

以下のステップに従えば、数分で OIDC 認証が利用できる環境が完成します。設定ミスを防ぐため、各項目は正確に入力してください。

Realm 作成 → Add realm → 任意の名前（例：demo-realm）で保存
Client 登録 → Clients > Create
Client ID: spring-boot-app
Client Protocol: openid-connect
Access Type: confidential（PKCE でも secret が必要）
Valid Redirect URIs: http://localhost:8080/login/oauth2/code/keycloak
Credentials タブで自動生成された client-secret をコピー

Spring 側設定例（導入文）

application.yml に OIDC クライアント情報を記述すれば、Spring Security が自動的に認可コードフローと PKCE を有効化します。環境変数でシークレットを管理すると、Docker/K8s との相性が良くなります。

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: spring-boot-app
            client-secret: ${KEYCLOAK_CLIENT_SECRET}
            authorization-grant-type: authorization_code
            redirect-uri: &quot;{baseUrl}/login/oauth2/code/{registrationId}&quot;
            scope: openid, profile, email
        provider:
          keycloak:
            issuer-uri: https://keycloak.example.com/realms/demo-realm

spring:

security:

oauth2:

client:

registration:

keycloak:

client-id: spring-boot-app

client-secret: ${KEYCLOAK_CLIENT_SECRET}

authorization-grant-type: authorization_code

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

scope: openid, profile, email

provider:

keycloak:

issuer-uri: https://keycloak.example.com/realms/demo-realm

OIDC 認証フローとトークン検証の実装

Spring Security が提供する oauth2Login() によって、認可コードフロー＋PKCE が自動的に有効化されます。本節ではフロー全体像とカスタム Claim マッピング方法を解説します。

認可コードフロー＋PKCE の構成（導入文）

Spring Security は内部で code verifier を生成し、トークンエンドポイントに送信するため、開発者はコードレベルでの実装が不要です。

Authorization Request: /oauth2/authorization/keycloak へリダイレクト
Code Exchange: PKCE verifier と共に認可コードをトークンエンドポイントへ送信

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(authz -&gt; authz
            .requestMatchers(&quot;/&quot;, &quot;/error&quot;).permitAll()
            .anyRequest().authenticated())
        .oauth2Login();   // OIDC ログインを有効化
    return http.build();
}

@Bean

SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

http.authorizeHttpRequests(authz -> authz

.requestMatchers("/", "/error").permitAll()

.anyRequest().authenticated())

.oauth2Login(); // OIDC ログインを有効化

return http.build();

}

アクセストークン・IDトークンの自動検証とカスタム Claim マッピング（導入文）

JwtDecoder が JWK エンドポイントから公開鍵を取得し、署名や exp、aud などを自動で検証します。追加クレームは OAuth2UserService を拡張して取得できます。

@Bean
OAuth2UserService&lt;OidcUserRequest, OidcUser&gt; oidcUserService() {
    OidcUserService delegate = new OidcUserService();
    return request -&gt; {
        OidcUser user = delegate.loadUser(request);
        Map&lt;String, Object&gt; claims = new HashMap&lt;&gt;(user.getClaims());
        String department = (String) claims.get(&quot;department&quot;);
        Set&lt;GrantedAuthority&gt; authorities = new HashSet&lt;&gt;(user.getAuthorities());
        if (&quot;admin&quot;.equals(department)) {
            authorities.add(new SimpleGrantedAuthority(&quot;ROLE_DEPT_ADMIN&quot;));
        }
        return new DefaultOidcUser(authorities, user.getIdToken(), user.getUserInfo());
    };
}

@Bean

OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {

OidcUserService delegate = new OidcUserService();

return request -> {

OidcUser user = delegate.loadUser(request);

Map<String, Object> claims = new HashMap<>(user.getClaims());

String department = (String) claims.get("department");

Set<GrantedAuthority> authorities = new HashSet<>(user.getAuthorities());

if ("admin".equals(department)) {

authorities.add(new SimpleGrantedAuthority("ROLE_DEPT_ADMIN"));

}

return new DefaultOidcUser(authorities, user.getIdToken(), user.getUserInfo());

};

}

ロール／権限マッピングと API 保護

Keycloak の Realm Role を Spring Security の GrantedAuthority に変換すれば、メソッドレベルの認可がシンプルに実装できます。

Role → GrantedAuthority の変換ロジック（導入文）

以下のコンバータを JwtAuthenticationConverter に登録するだけで、トークン内のロール情報が自動的に Spring の権限へマッピングされます。

@Component
public class KeycloakRoleConverter implements Converter&lt;Jwt, Collection&lt;GrantedAuthority&gt;&gt; {
    @Override
    public Collection&lt;GrantedAuthority&gt; convert(Jwt jwt) {
        List&lt;String&gt; roles = jwt.getClaimAsStringList(&quot;realm_access.roles&quot;);
        return roles.stream()
                .map(r -&gt; new SimpleGrantedAuthority(&quot;ROLE_&quot; + r.toUpperCase()))
                .collect(Collectors.toSet());
    }
}

@Component

public class KeycloakRoleConverter implements Converter<Jwt, Collection<GrantedAuthority>> {

@Override

public Collection<GrantedAuthority> convert(Jwt jwt) {

List<String> roles = jwt.getClaimAsStringList("realm_access.roles");

return roles.stream()

.map(r -> new SimpleGrantedAuthority("ROLE_" + r.toUpperCase()))

.collect(Collectors.toSet());

}

@PreAuthorize でエンドポイントを保護する例（導入文）

@PreAuthorize アノテーションにロール名を指定すれば、認可チェックが宣言的に行われます。

@RestController
@RequestMapping(&quot;/api&quot;)
public class SampleController {

    @GetMapping(&quot;/admin&quot;)
    @PreAuthorize(&quot;hasAuthority('ROLE_ADMIN')&quot;)
    public String adminEndpoint() {
        return &quot;管理者専用データ&quot;;
    }

    @GetMapping(&quot;/user&quot;)
    @PreAuthorize(&quot;hasAnyAuthority('ROLE_USER','ROLE_ADMIN')&quot;)
    public String userEndpoint() {
        return &quot;ユーザー向け情報&quot;;
    }
}

@RestController

@RequestMapping("/api")

public class SampleController {

@GetMapping("/admin")

@PreAuthorize("hasAuthority('ROLE_ADMIN')")

public String adminEndpoint() {

return "管理者専用データ";

}

@GetMapping("/user")

@PreAuthorize("hasAnyAuthority('ROLE_USER','ROLE_ADMIN')")

public String userEndpoint() {

return "ユーザー向け情報";

}

デプロイ・運用、マイグレーション、トラブルシューティング

本番環境でのコンテナ化や Kubernetes 展開手順、旧 Spring Adapter からの移行ポイント、およびよくあるエラーと対処法をまとめます。

Docker / Kubernetes での連携デプロイ例（導入文）

公式 Keycloak イメージと Spring Boot アプリを docker‑compose または Helm chart で組み合わせるだけで、開発・本番環境が統一的に構築できます。

# docker-compose.yml
version: &quot;3.9&quot;
services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.0.0
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
    ports:
      - &quot;8081:8080&quot;
    command: start-dev --http-relative-path /auth

  app:
    build: .
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}
    ports:
      - &quot;8080:8080&quot;
    depends_on:
      - keycloak

# docker-compose.yml

version: "3.9"

services:

keycloak:

image: quay.io/keycloak/keycloak:26.0.0

environment:

- KEYCLOAK_ADMIN=admin

- KEYCLOAK_ADMIN_PASSWORD=admin

ports:

- "8081:8080"

command: start-dev --http-relative-path /auth

app:

build: .

environment:

- SPRING_PROFILES_ACTIVE=prod

- KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}

ports:

- "8080:8080"

depends_on:

- keycloak

K8s 環境では codecentric/keycloakx Helm chart と Spring Boot の Deployment を組み合わせ、Ingress に OIDC のリダイレクト URI（例：/login/oauth2/code/keycloak）を設定します。

旧 Spring Adapter からのマイグレーション手順（導入文）

Red Hat が提供する移行ガイドに沿って、従来の keycloak-spring-boot-starter 系統を除去し、標準 OAuth2 クライアントへ置き換えます。

旧方式	新方式	主な変更点
`keycloak-spring-boot-starter`	Spring Security OIDC クライアント	アダプタ削除 → 標準フロー使用
`KeycloakSpringBootConfigResolver`	`spring.security.oauth2.client.provider.keycloak.issuer-uri`	設定ファイルがシンプル化
`KeycloakAuthenticationProvider`	`JwtAuthenticationConverter`	トークン検証ロジックが自動化

典型的なエラーと対処法（導入文）

実装時に遭遇しやすい問題とその解決策を一覧で示します。設定ミスの早期発見に役立ちます。

401/403 エラー：aud クレームが client-id と一致しているか確認。Keycloak の「Valid Redirect URIs」も正しいかチェック。
CORS 問題：Spring Security で CORS 設定を有効化し、Keycloak 側でも同一オリジンポリシーを許可する。
aud クレーム不一致：application.yml の issuer-uri が対象 Realm を正しく指しているか検証。

まとめ

Keycloak 26.0 は PKCE と標準 OIDC ログアウト機能をデフォルトで提供し、Spring Security 6 と即時統合可能です。
Spring Boot 3.x + Spring Security 6 の oauth2Login() によって認可コードフローとトークン検証が自動化され、実装コストを大幅に削減できます。
Realm/Client 設定 は管理コンソールでシンプルに完了し、application.yml へ issuer-uri とクレデンシャルを書くだけで接続が確立します。
ロールマッピング はカスタム JwtAuthenticationConverter／KeycloakRoleConverter によって実装し、@PreAuthorize でメソッド単位の保護が可能です。
Docker/Kubernetes 環境 では公式イメージと Helm chart を活用し、シークレットは環境変数または K8s Secret で安全に管理します。
旧 Adapter からの移行 は Red Hat のマイグレーションガイドに従い、設定を標準 OAuth2 に置き換えるだけで完了します。

以上の手順とベストプラクティスに沿って構築すれば、最新の Keycloak と Spring Security を組み合わせた安全・拡張性の高い認証基盤が短時間で実現できます。

スポンサードリンク

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

スポンサードリンク

働き方から選べる

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

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

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

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

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

Beyond Careerに無料相談する

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

-KeyCloak

comment コメントをキャンセル

: KeyCloak

Keycloak Docker デプロイの最新ガイドライン

本記事では公式イメージ選定やセキュリティ設定、Docker Composeでの外部DB接続手順など、Keycloakプロダクション環境構築の最新ガイドラインを解説。

: KeyCloak

Windows向けKeycloakインストールとAD連携ガイド（2026年版）

KeycloakのWindows導入からADフェデレーション、Kerberos認証、Entra IDブローカー設定までを網羅的に紹介します。

: 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 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で実現するマルチテナントSaaS向けID管理と自動化ガイド

本稿では、TC3が提示するID/アカウント管理要件を踏まえ、Keycloak のレルム単位分離と共有レルム＋属性方式の比較、ポリシーベース認可やイベントリスナー活用方法、kcadm.sh・Terraform・Ansibleによるテナント自動プロビジョニング手順を詳しく紹介します。

EnvoyとIstioの比較：サービスメッシュとデータプレーンの役割分離

Envoy Proxy Docker導入ガイド - ロードバランシングとセキュリティ設定

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

Keycloak 26.0（Red Hat ビルド）の新機能と OIDC 標準サポート

主な変更点の概要

OpenID Connect と PKCE の統合的な解説

OIDC の基本フローモデル（概要）

PKCE（Proof Key for Code Exchange）とは

Realm とクライアントの基本概念

Realm の概要（導入文）

Client の概要（導入文）

Spring Boot 3.x と Spring Security 6 の基本構成

プロジェクト雛形の作り方（導入文）

依存関係とバージョン管理（導入文）

Keycloak 側の Realm／Client 作成と Spring 設定

Realm と Client の作成手順（導入文）

Spring 側設定例（導入文）

OIDC 認証フローとトークン検証の実装

認可コードフロー＋PKCE の構成（導入文）

アクセストークン・IDトークンの自動検証とカスタム Claim マッピング（導入文）

ロール／権限マッピングと API 保護

Role → GrantedAuthority の変換ロジック（導入文）

@PreAuthorize でエンドポイントを保護する例（導入文）

デプロイ・運用、マイグレーション、トラブルシューティング

Docker / Kubernetes での連携デプロイ例（導入文）

旧 Spring Adapter からのマイグレーション手順（導入文）

典型的なエラーと対処法（導入文）

まとめ

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

Keycloak 26.0（Red Hat ビルド）の新機能と OIDC 標準サポート

Spring Boot 3.x と Spring Security 6 の基本構成