プレビュー版
PocketSign Link v2 は現在プレビュー版です。正式提供までに仕様が変更される可能性があります。
OIDC の概要
PocketSign Link v2 は KLON IdP サーバーに実装された OpenID Connect と OAuth 2.0 を使って、サービスに対するログイン、ユーザー識別、リソースアクセス権限の付与を提供します。 ブラウザベースの基本フローは Authorization Code Flow です。
:::info この章と標準仕様の関係 PocketSign Link v2 の OIDC は、閉じた独自仕様ではありません。詳細を知りたい場合は、以下の標準仕様をご参照ください。
- OpenID Connect Core 1.0
- OpenID Connect Discovery 1.0
- OAuth 2.0 Authorization Framework (RFC 6749)
- OAuth 2.0 Token Revocation (RFC 7009)
- Proof Key for Code Exchange (RFC 7636)
- OAuth 2.0 Token Introspection (RFC 7662)
- Pushed Authorization Requests (RFC 9126)
- Rich Authorization Requests (RFC 9396)
:::
OIDC 連携でできること
PocketSign Link v2 と OIDC 連携すると、サービスは主に次のことができるようになります。
- KLON のアカウントでユーザーを認証する
- サービス ごとの サブスクリプションID を使ってユーザーを識別する
- ID トークンで認証結果と基本的な属性を受け取る
- アクセストークンを使って API を呼び出す
prompt=login、max_age、acr_valuesを使って再認証を要求する
最初にイメージしたい基本シーケンス
OIDC 連携の最短イメージは、次の流れです。
- サービス が 認可エンドポイント にユーザーをリダイレクトする
- KLON がログイン、必要なら再認証や同意を行う
- サービス が認可コードを受け取り、トークンエンドポイント でトークンに交換する
- サービス は IDトークン や アクセストークン を用いることで、ユーザー情報を取得する
最低限必要になるリクエスト
典型的な Web サービス連携では、まず次の 2 つを押さえると全体像をつかみやすくなります。
| フェーズ | 代表リクエスト | 役割 |
|---|---|---|
| 認可開始 | GET /api/oidc/v1/authorize | ログイン、再認証、同意、認可コード発行の起点 |
| トークン取得 | POST /api/oidc/v1/token | 認可コードを access_token / id_token / refresh_token に交換 |
IDトークン・アクセストークンにおける sub の意味
PocketSign Link v2 の IDトークン・アクセストークンにおける sub はサービスごとの subscription_id が入ります。
主要なエンドポイント
Issuer のベース URL は環境ごとに異なります。
固定のホスト名を前提にせず、まず /.well-known/openid-configuration を取得してください。
| エンドポイント | メソッド | 用途 |
|---|---|---|
/.well-known/openid-configuration | GET | Discovery Document を取得します |
/api/oidc/v1/jwks | GET | ID トークンやアクセストークンの検証に使う公開鍵を取得します |
/api/oidc/v1/authorize | GET | 認可リクエストを開始します |
/api/oidc/v1/par | POST | Pushed Authorization Request を登録し request_uri を発行します |
/api/oidc/v1/token | POST | 認可コード、リフレッシュトークン、またはクライアントクレデンシャルをトークンに交換します |
/api/oidc/v1/userinfo | GET, POST | アクセストークンに対応する最新のユーザー属性を取得します |
/api/oidc/v1/introspect | POST | アクセストークンまたはリフレッシュトークンの有効性を照会します |
/api/oidc/v1/revoke | POST | トークンを明示的に失効します |
サポートしている基本仕様
| 項目 | サポート内容 |
|---|---|
response_type | code のみ |
grant_type | authorization_code, refresh_token |
response_mode | query |
| PKCE | S256 のみ |
prompt | none, login, consent |
| クライアント認証 | client_secret_basic, client_secret_post, private_key_jwt, none (ネイティブアプリのみ) |
| Rich Authorization Requests | authorization_details をサポート |
| DPoP | 対応。proof の署名アルゴリズムは ES256 のみ |
実装判断で迷いやすい項目
- クライアント設定の意味は クライアント設定
- クライアント認証の送り方は クライアント認証
- 個別権限要求と同意モデルは authorization_details と同意モデル
ログアウト連携をしたい場合
PocketSign Link v2 でセッションが終了したときに サービス 側のセッションも自動的に無効化したい場合は、Back-Channel Logout を参照してください。
ユースケース別に読みたい場合
具体的な導入イメージを先に掴みたい場合は、次のページから読むのが分かりやすいです。