Token Management

トークン管理（Token Management）開発ガイド

ドキュメント

• documentation/docs/content_06_developer-guide/03-application-plane/03-token-endpoint.md - トークンエンドポイント実装ガイド
• documentation/docs/content_03_concepts/04-tokens-claims/concept-02-token-management.md - トークン管理概念

機能概要

トークン管理は、Access Token/Refresh Token/ID Tokenの発行・検証・取消を行う層。

• トークン発行: Authorization Code, Refresh Token, Client Credentials各グラント対応
• Token Introspection（RFC 7662）: トークン検証
• Token Revocation（RFC 7009）: トークン取消
• ID Token発行: OpenID Connect対応

モジュール構成

libs/
├── idp-server-core/                         # トークンコア
│   └── .../token/
│       ├── handler/token/
│       │   └── TokenRequestHandler.java    # トークンリクエスト処理
│       ├── service/
│       │   ├── OAuthTokenCreationServices.java
│       │   ├── AuthorizationCodeGrantService.java
│       │   ├── RefreshTokenGrantService.java
│       │   └── ClientCredentialsGrantService.java
│       ├── OAuthToken.java                 # トークン表現
│       ├── repository/
│       │   ├── OAuthTokenCommandRepository.java
│       │   └── OAuthTokenQueryRepository.java
│       └── handler/
│           ├── tokenintrospection/
│           │   └── TokenIntrospectionHandler.java
│           └── tokenrevocation/
│               └── TokenRevocationHandler.java
│
├── idp-server-core-adapter/                 # アダプター（キャッシュ含む）
│   └── .../datasource/token/
│       ├── OAuthTokenCacheKeyBuilder.java   # キャッシュキー生成（共有）
│       ├── OAuthTokenCacheStoreResolver.java # TOKEN_CACHE_ENABLED制御
│       ├── command/
│       │   └── OAuthTokenCommandDataSource.java  # 削除時キャッシュ連動
│       └── query/
│           └── OAuthTokenQueryDataSource.java    # Introspection時キャッシュ
│
└── idp-server-control-plane/               # 管理API
    └── .../management/token/
        └── TokenConfigManagementApi.java

トークン発行

idp-server-core/token/handler/token/TokenRequestHandler.java 内の実際のメソッドシグネチャ:

public class TokenRequestHandler {

    OAuthTokenCreationServices oAuthTokenCreationServices;

    public TokenRequestResponse handle(
        TokenRequest tokenRequest,
        PasswordCredentialsGrantDelegate passwordCredentialsGrantDelegate,
        TokenUserFindingDelegate tokenUserFindingDelegate
    ) {
        // Grant typeに応じた処理はOAuthTokenCreationServicesが管理
        // AuthorizationCodeGrantService
        // RefreshTokenGrantService
        // ClientCredentialsGrantService
        // ...
    }
}

注意: Grant type別の処理は、OAuthTokenCreationServices経由で各Serviceに委譲されます。

Grant type別サービス

JWT Bearer Grant（RFC 7523）

JWT Bearer Grantは、JWTアサーションを使用してアクセストークンを直接取得するグラントタイプです。

概要

• Grant Type: urn:ietf:params:oauth:grant-type:jwt-bearer
• 用途: 外部IdPトークン交換、デバイス認証によるトークン取得
• 仕様: RFC 7523

サポートするフェデレーションタイプ

クライアント設定

{
  "grant_types": ["urn:ietf:params:oauth:grant-type:jwt-bearer"],
  "extension": {
    "available_federations": [
      {
        "issuer": "device",
        "type": "device",
        "jwt_bearer_grant_enabled": true
      },
      {
        "issuer": "https://accounts.google.com",
        "provider_id": "google",
        "type": "oidc",
        "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
        "jwt_bearer_grant_enabled": true
      }
    ]
  }
}

トークンリクエスト

POST /v1/tokens
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=<JWT>
&scope=openid profile

JWT Assertion構造（デバイスタイプ）

// Header
{
  "alg": "HS256",
  "typ": "JWT"
}
// Payload
{
  "iss": "device:{deviceId}",
  "sub": "{deviceId}",
  "aud": "https://idp.example.com/{tenantId}",
  "jti": "unique-token-id",
  "iat": 1234567890,
  "exp": 1234571490
}

ユーザー解決ロジック（subject_claim_mapping）

JWTのsubクレームからユーザーを解決する方法を設定できます。

外部IdPフェデレーションの動作:

• JWTのsubは外部IdPでのユーザー識別子（idp-serverのユーザーIDではない）
• findByExternalIdpSubject(tenant, subject, providerId)で検索
• providerIdはフェデレーション設定のprovider_idから取得（未設定の場合はissuerにフォールバック）
• 事前に外部IdP連携（Federation）でユーザーが紐付けられている必要あり

provider_id設定:

{
  "issuer": "https://accounts.google.com",
  "provider_id": "google",  // ユーザー検索時に使用（DDL制約対応）
  "type": "oidc"
}

• provider_idを明示的に設定することで、長いissuer URLではなく短い識別子でユーザー検索が可能
• DDLのVARCHAR(255)制約に対応
• 未設定の場合はissuerがそのまま使用される（後方互換性）

セキュリティ上の利点（device_id方式）:

• クライアントがユーザーIDを知る必要がない
• デバイスシークレット漏洩時も、そのデバイス所有者としてのみ認証可能
• 任意ユーザーへのなりすまし不可

関連ファイル

Token Introspection（RFC 7662）

idp-server-core/token/introspection/ 内:

トークンのメタデータを検証し、active/inactiveを返却します。

Introspectionキャッシュ

TOKEN_CACHE_ENABLED=true（環境変数）かつRedis有効時、Introspection結果をRedisにキャッシュします。

• パターン: Cache-Aside（初回Introspection時にキャッシュ格納）
• キー: oauth_token:at:{tenant_id}:{hmac(access_token)}（OAuthTokenCacheKeyBuilderで生成）
• TTL: 60秒固定
• デフォルト: OFF（opt-in）。OAuthTokenCacheStoreResolverがTOKEN_CACHE_ENABLEDを参照し、OFFの場合はNoOperationCacheStoreを使用

キャッシュ削除の連鎖

トークンが削除される全パターンでキャッシュも連動して削除されます:

Token Revocation（RFC 7009）

idp-server-core/token/revocation/ 内:

トークンを無効化します。OAuthTokenCommandRepository.delete()を使用します。キャッシュが有効な場合、DB削除と同時にキャッシュも削除されます。

E2Eテスト

e2e/src/tests/
├── spec/
│   ├── rfc6749_token_endpoint_*.test.js     # OAuth 2.0 Token Endpoint
│   ├── rfc7009_token_revocation_*.test.js   # Token Revocation
│   ├── rfc7662_token_introspection_*.test.js # Token Introspection
│   ├── rfc7523_jwt_bearer_grant_*.test.js   # JWT Bearer Grant
│   └── oidc_core_*.test.js                  # OIDC関連トークンテスト
│
├── usecase/device-credential/
│   └── device-credential-04-device-secret-issuance.test.js  # デバイスシークレット+JWT Bearer
│
└── scenario/application/
    └── (トークン関連シナリオテスト)

コマンド

# ビルド
./gradlew :libs:idp-server-core:compileJava

# テスト
cd e2e && npm test -- spec/rfc6749_token_endpoint_*.test.js
cd e2e && npm test -- spec/rfc7009_token_revocation_*.test.js
cd e2e && npm test -- spec/rfc7662_token_introspection_*.test.js
cd e2e && npm test -- spec/rfc7523_jwt_bearer_grant_*.test.js
cd e2e && npm test -- usecase/device-credential/device-credential-04-device-secret-issuance.test.js

トラブルシューティング

トークン発行失敗

• Grant typeが正しいか確認
• Authorization Code/Refresh Tokenが有効か確認
• 対応するGrantServiceが登録されているか確認

Introspectionでinactive

• トークンが有効期限内か確認
• OAuthTokenが正しく保存されているか確認

Introspectionキャッシュが効かない

• TOKEN_CACHE_ENABLED=trueが環境変数に設定されているか確認
• CACHE_ENABLE=true（Redis自体）が有効か確認
• OAuthTokenCacheStoreResolverがNoOperationCacheStoreを返していないか確認

トークン失効後もIntrospectionでactiveが返る

• キャッシュTTL（60秒）以内の場合、古いキャッシュが返される可能性がある
• 通常はRevocation/削除時にキャッシュも連動削除されるため発生しない
• 直接DBを操作した場合のみ不整合が起きうる（最大60秒で自動解消）

Revocationが失敗

• クライアント認証が成功しているか確認
• OAuthTokenCommandRepository.delete()が正しく呼ばれているか確認

JWT Bearer Grant失敗

invalid_grant: Device federation not configured

• クライアント設定のavailable_federationsにtype: "device"が含まれているか確認
• jwt_bearer_grant_enabled: trueが設定されているか確認

invalid_grant: Invalid JWT signature

• デバイスシークレットが正しいか確認
• JWTのalgがデバイス設定と一致しているか確認（HS256/HS384/HS512）
• 手動JWT生成の場合、署名エンコードが正しいか確認（Base64URL）

invalid_grant: User not found

• JWTのsubクレームにデバイスIDが設定されているか確認
• subject_claim_mappingの設定を確認（デフォルト: device_id）
• デバイスが正しくユーザーに紐付いているか確認

invalid_client

• クライアント認証方式が正しいか確認（client_secret_basic vs client_secret_post）
• AuthorizationヘッダーのBasic認証が正しくエンコードされているか確認