Contents
- 1 Keycloak OIDC カスタムクレーム設定方法の実践ガイド
- 2 Keycloakでカスタムクレームを定義する前に知っておくべきOIDCの基礎
- 3 Keycloak Realm設定でカスタムアトリビュートを追加する手順
- 4 トークン生成時のJSON Web Token構造とカスタムクレーム埋め込み
- 5 Spring Securityでのカスタムクレーム取得処理サンプル
- 6 実環境での検証フローとトラブルシューティングポイント
- 7 Keycloak管理画面でのカスタムクレーム設定実践ガイド
- 8 Spring Security 5.x以降でのJwt API対応と互換性確保
- 9 Keycloakバージョンの影響と対応策
- 10 まとめと今後の課題
Keycloak OIDC カスタムクレーム設定方法の実践ガイド
KeycloakでOIDC経由のカスタムクレームを正しく設定するには、トークン発行フローに即した構成が不可欠です。本記事では、Java開発者やDevOpsエンジニア向けに、Realm設定からSpring Securityでの実装までの一連の手順とコードサンプルを解説します。OIDCプロトコルの理解と具体的な構成例を通じて、実環境での課題に対応する方法をご案内します。
Keycloakでカスタムクレームを定義する前に知っておくべきOIDCの基礎
OIDC（OpenID Connect）はOAuth 2.0プロトコルに基づく認証フレームワークで、ユーザーに関する情報を「claim」としてトークンに埋め込む仕組みが特徴です。カスタムクレームが必要になるのは、標準的なclaim（例：sub, email）では表現できないユースケースを想定するためです。
OIDCプロトコルにおけるclaimの役割と種類
| 項目 | 説明 |
|---|---|
| 標準Claim | OIDC仕様で定義されたもの（例：iss, exp, name）。常にトークンに含まれる。 |
| カスタムClaim | システム固有の情報を追加するための拡張機能。開発者による自由な定義が可能。 |
標準的なclaimは認証フローで必要不可欠ですが、企業独自の属性（例：所属部署、社員番号）をアプリケーションに渡すにはカスタムクレームが有効です。
Keycloak Realm設定でカスタムアトリビュートを追加する手順
Keycloakでカスタムクレームを活用するには、ユーザー属性の定義とRealmレベルでの構成が必要です。以下にステップバイステップの操作方法を解説します。
Realm設定画面へのアクセス方法
- Keycloak管理画面（例：
http://localhost:8080/auth/admin/realms）を開き、対象のRealmを選択。 - 「Users」 → 「User Attributes」 からカスタムフィールドを追加する。
ユーザー属性のカスタムフィールド作成プロセス
- 1. 新規アトリビュートの登録
- 名前（Name）：
custom_department - 値（Value）：所属部署名（例：
Engineering） - データ型（Data Type）：
String - 2. 必須項目設定（任意）
- 「Required」にチェックを付けると、ユーザー登録時に入力が必須になる。
注意: カスタムアトリビュートはロールベースで制限でき、セキュリティポリシーに応じてアクセス権を細分化できます。
トークン生成時のJSON Web Token構造とカスタムクレーム埋め込み
JWT（JSON Web Token）にはヘッダー、ペイロード、署名の3つのセクションが存在します。カスタムクレームはペイロードに格納され、アプリケーション側で解析されます。
JWTペイロードの構成要素
| セクション | 説明 |
|---|---|
iss |
イシュアー（Keycloak） |
sub |
ユーザーID（subject） |
custom_department |
カスタムアトリビュートの値がここに記録される |
カスタムクレームのフィールド名規約
- スネークケースを推奨（例：
custom_department） - OIDC標準claimと重複しないようにする
- リフレッシュトークンにはカスタムクレームは含まれない点に注意
実際のトークン例：
|
1 2 3 4 5 6 |
{ "iss": "https://keycloak.example.com/auth/realms/myrealm", "sub": "abc123xyz", "custom_department": "Engineering" } |
Spring Securityでのカスタムクレーム取得処理サンプル
Spring Securityでカスタムクレームを抽出するには、OAuth2ResourceServerの設定とクレーム解析ロジックが必要です。
OAuth2ResourceServerの設定（application.yml）
|
1 2 3 4 5 6 7 |
spring: security: oauth2: resourceserver: jwt: jwk-set-uri: https://keycloak.example.com/auth/realms/myrealm/.well-known/openid-configuration/jwks |
カスタム属性のパースロジック（Javaコード）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
import org.springframework.security.core.annotation.AuthenticationPrincipal; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class UserController { @GetMapping("/user/department") public String getDepartment(@AuthenticationPrincipal Jwt jwt) { return jwt.getClaimAsString("custom_department"); } } |
注意:
JwtクラスはSpring Securityのorg.springframework.security.oauth2.jwt.Jwtをインポートする必要があります。
初心者向け解説:Jwtクラスを使用する際は、import org.springframework.security.oauth2.jwt.Jwt;を忘れず記述してください。
実環境での検証フローとトラブルシューティングポイント
カスタムクレームが正しく動作しない場合は、以下の手順でデバッグします。
トークン発行時のログ確認手順
- Keycloakのログ設定を
DEBUGレベルに変更し、トークン生成プロセスを観察。 - Spring SecurityのログからJWT解析エラーの有無をチェック。
クレームが反映されないケースの原因分析
| 原因 | 対処法 |
|---|---|
| フィールド名ミス | カスタムアトリビュートの名称と一致するか確認 |
| トークンタイプの不一致 | アクセストークンにのみカスタムクレームが含まれる |
| Spring Securityの設定漏れ | Jwtクラスで正しく取得しているか再確認 |
Keycloak管理画面でのカスタムクレーム設定実践ガイド
ここまでの手順を踏まえ、実際にKeycloak管理画面でカスタムクレームをテストしてみましょう。
テストユーザー作成とアトリビュート値の確認
- 「Users」 → 「Create User」 をクリック。
- 「User Attributes」 セクションに
custom_departmentに値を入力し、保存。
ユースケース例: 部署別アクセス制限が必要なアプリケーションでは、
custom_departmentの値に基づいて権限処理を行う。
トークン発行APIの呼び出し方法
-
アクセストークンを取得するためのAPIコール（例：curl）
bash
curl -X POST http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=your-client-id" \
-d "username=testuser" \
-d "password=secret" -
レスポンス内の
access_tokenを解析し、カスタムクレームが含まれているか確認。
Keycloak管理画面での設定は一見単純ですが、実際のアプリケーションとの連携には細かな手順が必要です。今回の手順をもとに、自社環境で検証してみてください。
Spring Security 5.x以降でのJwt API対応と互換性確保
Spring Security 5.3以降では、OAuth2AuthenticationTokenからJwt型の取得が推奨されています。以下に互換性を考慮したコード例を示します。
複数バージョン対応設定（application.yml）
|
1 2 3 4 5 6 7 |
spring: security: oauth2: resourceserver: jwt: jwk-set-uri: https://keycloak.example.com/auth/realms/myrealm/.well-known/openid-configuration/jwks |
バージョン別対応コード（Java）
Spring Security 5.3+
|
1 2 |
import org.springframework.security.oauth2.jwt.Jwt; |
Spring Security 5.1〜5.2
|
1 2 |
import org.springframework.security.oauth2.core.OAuth2AuthenticatedPrincipal; |
注意: Spring Security 5.x以降では、
getClaimAsString()メソッドが非推奨となる場合があります。代わりにJwt.getClaims()を使用し、型変換を行う必要があります。
Keycloakバージョンの影響と対応策
Keycloak v21.0以降で導入されたUser Attributeのclaim設定オプションにより、カスタムアトリビュートを自動的にJWTペイロードに追加できるようになりました。
Keycloakバージョン別の変更点
| バージョン | 設定方法 | 互換性注意点 |
|---|---|---|
| v21.0+ | User Attributes → Claim設定 |
カスタムアトリビュートが自動的にトークンに含まれる |
| v20.0以下 | 手動でJWT構造をカスタマイズ必要 | リアルタイム反映に時間がかかる |
実装例: Keycloak v21.0以降では、
custom_departmentを「Claim」セクションに登録することで、トークンへの自動挿入が可能になります。
まとめと今後の課題
本記事では、Keycloakでのカスタムクレームの設定手順やSpring Securityとの連携方法について解説しました。実装上は、ユーザー属性の正しい定義とコード側での適切な解析処理が重要です。
今後の課題として、以下のようなケースに該当する場合は、さらなる検証が必要です:
- リアルタイムで変更されたカスタムクレームが即座に反映されるか。
- 複数のRealm間でのカスタムクレームの一貫性管理。
これらの点を踏まえ、自社環境に最適な構成をご検討ください。