Grant管理（Grant Management）開発ガイド

Grant管理（Grant Management）開発ガイド

ドキュメント

• documentation/​docs/​content_03_concepts/​03-authentication-authorization/​concept-05-grant-management.md - Grant管理概念
• documentation/​openapi/​swagger-grant-management-ja.yaml - Grant管理API仕様（OpenAPI）

機能概要

Grant管理は、認可コンテキストを管理する層。

• AuthorizationGrant: ユーザー、認証、クライアント、スコープの複合構造
• AuthorizationGranted: 永続化されたGrant（created_at/​updated_at含む）
• ConsentClaims: 同意情報の管理
• Scopeベース同意: クライアント別にscopeを記録
• Grant管理API: 管理者向けのGrant一覧取得・詳細取得・取り消しAPI

モジュール構成

libs/
├── idp-server-core/                         # Grantコア
│   └── .../​grant_management/
│       ├── AuthorizationGranted.java        # 永続化Grant（created_at/​updated_at含む）
│       ├── AuthorizationGrantedIdentifier.java
│       ├── AuthorizationGrantedQueries.java # クエリパラメータ（limit上限1000）
│       ├── AuthorizationGrantedRepository.java
│       ├── AuthorizationGrantedQueryRepository.java
│       ├── grant/
│       │   ├── AuthorizationGrant.java      # 認可Grant
│       │   ├── GrantIdTokenClaims.java
│       │   └── GrantUserinfoClaims.java
│       └── consent/
│           └── ConsentClaims.java           # 同意情報
│
├── idp-server-core-adapter/                 # DB実装
│   └── .../​grant_management/
│       ├── AuthorizationGrantedDataSource.java
│       ├── AuthorizationGrantedQueryDataSource.java
│       ├── ModelConverter.java              # DB→モデル変換
│       ├── PostgresqlExecutor.java
│       └── MysqlExecutor.java
│
├── idp-server-control-plane/                # Grant管理API定義
│   └── .../​management/​oidc/​grant/
│       ├── OrgGrantManagementApi.java       # APIインターフェース
│       ├── GrantManagementContext.java
│       ├── GrantManagementContextBuilder.java
│       ├── handler/
│       │   ├── OrgGrantManagementHandler.java
│       │   ├── GrantManagementService.java
│       │   ├── GrantFindListService.java
│       │   ├── GrantFindService.java
│       │   └── GrantRevocationService.java  # Grant取り消し+トークン削除
│       └── io/
│           ├── GrantManagementRequest.java
│           ├── GrantManagementResponse.java
│           ├── GrantManagementResult.java
│           └── GrantManagementStatus.java
│
├── idp-server-use-cases/                    # EntryService
│   └── .../​control_plane/​organization_manager/
│       └── OrgGrantManagementEntryService.java
│
└── idp-server-springboot-adapter/           # REST API
    └── .../​control_plane/​restapi/​organization/
        └── OrganizationGrantManagementV1Api.java

Grant管理API（Organization Level）

エンドポイント

クエリパラメータ（一覧取得）

dry_runモード

DELETE時に ?dry_run=true を指定すると、実際の削除を行わずシミュレーション結果を返す。

Grant取り消し時の動作

Grant削除時に、同じuser+clientの全トークン（アクセストークン、リフレッシュトークン）も削除される（Auth0スタイル）。

AuthorizationGranted構造

public class AuthorizationGranted {
    AuthorizationGrantedIdentifier identifier;
    AuthorizationGrant authorizationGrant;
    LocalDateTime createdAt;
    LocalDateTime updatedAt;

    public Map<String, Object> toMap() {
        // id, user, client, scopes, created_at, updated_at を返す
    }
}

AuthorizationGrant構造

public class AuthorizationGrant {
    TenantIdentifier tenantIdentifier;
    User user;
    Authentication authentication;
    RequestedClientId requestedClientId;
    ClientAttributes clientAttributes;
    GrantType grantType;
    Scopes scopes;
    GrantIdTokenClaims idTokenClaims;
    GrantUserinfoClaims userinfoClaims;
    CustomProperties customProperties;
    AuthorizationDetails authorizationDetails;
    ConsentClaims consentClaims;
}

Grantが作成されるタイミング

• Authorization Code Flowでの同意時
• Password Grantでのトークン発行時（スコープはマージされる）
• その他のGrant Typeでのトークン発行時

E2Eテスト

e2e/​src/​tests/
├── usecase/​standard/
│   └── standard-05-grant-revocation.test.js   # Grant取り消しE2E
└── scenario/​control_plane/​organization/
    └── organization_grant_management.test.js  # Grant管理APIテスト

コマンド

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

# E2Eテスト
cd e2e && npm test -- src/​tests/​usecase/​standard/​standard-05-grant-revocation.test.js
cd e2e && npm test -- src/​tests/​scenario/​control_plane/​organization/​organization_grant_management.test.js

トラブルシューティング

Grantが見つからない

• AuthorizationGrantedが正しく生成されているか確認
• ユーザー、認証、クライアント情報が揃っているか確認
• Password Grantの場合、ResourceOwnerPasswordCredentialsGrantServiceでGrant作成ロジックを確認

Grant取り消し後もトークンが有効

• GrantRevocationServiceでdeleteByUserAndClientが呼ばれているか確認
• トランザクションが正しくコミットされているか確認

created_at/​updated_atがレスポンスに含まれない

• ModelConverter.parseLocalDateTime()が正しくパースしているか確認
• DBからのtimestamp形式を確認（LocalDateTimeParserで対応）