バックエンド連携 (機能) | Accountmaker ドキュメント

バックエンド連携

AccountMaker（以下「AM」）は JWKS で公開鍵を、OIDC Discovery で設定情報を公開します。どの JWT ライブラリでも利用できる標準プロトコルです。

トークンをローカルで検証し、クレームを信頼してリクエストを認可します。

トークン検証フロー

エンドポイント

Endpoint	Purpose
`/.well-known/jwks.json`	公開署名鍵
`/.well-known/openid-configuration`	OIDC Discovery ドキュメント
`/oauth2/introspect`	Refresh Token の検査

JWKS

ローカル検証用の公開鍵を取得します。

GET /.well-known/jwks.json

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key_...",
      "alg": "RS256",
      "n": "0vx7agoebG...",
      "e": "AQAB"
    }
  ]
}

ローテーション期間中は複数鍵が返る場合があります。JWT ヘッダーの kid と一致する鍵を使用してください。

OIDC Discovery

Discovery ドキュメントにより、クライアントを自動設定できます。

GET /.well-known/openid-configuration

OpenID Connect Discovery 仕様に基づき、エンドポイント、対応アルゴリズム、機能が返されます。

JWT クレーム

検証済みトークンには次が含まれます。

Claim	Description
`iss`	発行者 URL
`sub`	Subject（ユーザー ID または Client ID）
`aud`	想定オーディエンス
`exp`	有効期限（Unix timestamp）
`iat`	発行時刻（Unix timestamp）
`scope`	付与済み権限
`cid`	Client ID
`app`	Application ID
`acc`	現在の Account ID
`uid`	User ID（ユーザー認証時）
`role`	現在の Account でのロール

キャッシュ

JWKS 応答をキャッシュする（ETag / If-None-Match を利用）
署名検証失敗時に再取得する（鍵ローテーション対応）
典型的な TTL は 1 時間

トークンイントロスペクション

Refresh Token、または厳密な検証が必要な場合に使用します。

POST /oauth2/introspect
Content-Type: application/x-www-form-urlencoded

token=...&client_id=...&client_secret=...

active: true/false とトークンクレームが返されます。Access Token は JWT のため、可能な限り JWKS によるローカル検証を推奨します。