クライアント認証

このページでは、PocketSign Link v2 OIDC のサーバー間通信で使うクライアント認証について説明します。

どこで必要か

クライアント認証が必要なのは、サービス と PocketSign Link v2 が直接通信するエンドポイントです。

エンドポイント	クライアント認証
POST /api/oidc/v1/par	必要
POST /api/oidc/v1/token	必要
POST /api/oidc/v1/introspect	必要
POST /api/oidc/v1/revoke	必要
GET /api/oidc/v1/authorize	不要
GET/POST /api/oidc/v1/userinfo	不要。アクセストークンで認可

サポート方式

• client_secret_basic
• client_secret_post
• private_key_jwt

client_secret_basic

HTTP Basic 認証で client_id:client_secret を送る方式です。

例

curl -X POST "https://id.mock.klon.you/api/oidc/v1/token" \
  -u "7f3b41e2-a81c-4e35-b08d-2c7e60a4d073:client-secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=SplxlOBeZQQYbYS6WxSbIA" \
  -d "redirect_uri=https://rp.example.com/callback" \
  -d "code_verifier=random-verifier"

向いている場面

• 一般的なサーバーサイド Web RP
• まず最小構成で導入したいとき

注意点

• client_secret をフロントエンドへ配布しない
• ログに Authorization ヘッダーを出さない

client_secret_post

フォームパラメータとして client_id と client_secret を送る方式です。

例

curl -X POST "https://id.mock.klon.you/api/oidc/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=7f3b41e2-a81c-4e35-b08d-2c7e60a4d073" \
  -d "client_secret=client-secret" \
  -d "grant_type=authorization_code" \
  -d "code=SplxlOBeZQQYbYS6WxSbIA" \
  -d "redirect_uri=https://rp.example.com/callback" \
  -d "code_verifier=random-verifier"

注意点

• フォーム本文をそのままログに出す実装では漏えいリスクが上がる
• 基本的には client_secret_basic のほうが扱いやすいことが多い

private_key_jwt

client_assertion で JWT を送り、クライアント秘密鍵で認証する方式です。

送るパラメータ

パラメータ	役割
client_id	クライアント ID
client_assertion_type	urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion	署名済み JWT

client_assertion に最低限入れるもの

クレーム	典型値
iss	client_id
sub	client_id
aud	対象エンドポイント URL
jti	一意な JWT ID
iat	発行時刻
exp	短い有効期限

例

curl -X POST "https://id.mock.klon.you/api/oidc/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=7f3b41e2-a81c-4e35-b08d-2c7e60a4d073" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=<signed_client_assertion_jwt>" \
  -d "grant_type=authorization_code" \
  -d "code=SplxlOBeZQQYbYS6WxSbIA" \
  -d "redirect_uri=https://rp.example.com/callback" \
  -d "code_verifier=random-verifier"

前提

• クライアント設定に jwks_uri が必要です
• KLON は jwks_uri からクライアント公開鍵を取得して assertion を検証します

向いている場面

• クライアントシークレット共有を避けたい
• 鍵ローテーションを JWKS ベースで運用したい

よくあるエラー

エラー	説明
invalid_client	認証情報が無効、または送信方法がクライアントの登録方式と一致しない
invalid_client	client_secret が古い、再発行済み、またはクライアントID/シークレットの組み合わせが誤っている
invalid_request	client_assertion_type が不足している、または不正な値が指定されている
invalid_grant	認可コードや redirect_uri が不一致、またはクライアント認証が適切に行われていない
assertion 検証失敗	aud、iss、sub、署名鍵など JWT のクレームや鍵が想定と違う

関連ページ

• 設定項目の意味は クライアント設定
• token の基本は トークン
• セキュリティ観点は OIDC / OAuth2 セキュリティ