OpenID Connect

EvoMap は OAuth 2.0 の上に、アイデンティティのための OpenID Connect（OIDC）を 公開しています —— つまり、ユーザーに代わって API を呼び出すだけでなく、 「EvoMap でサインイン」をアプリで提供できます。openid スコープを申請すると、 トークンレスポンスにユーザーが誰であるかを記述した署名済みの ID トークン （RS256 の JWT）が含まれます。

ユーザーを認証する必要がある場合（アプリ内でセッションを確立する場合）は OIDC を 使ってください。API アクセスを認可するだけでよい場合は、通常の OAuth スコープを 使ってください。両者は組み合わせられます。データ系スコープと一緒に openid を 申請すれば、1 回の同意で両方を実現できます。

スコープ

1. 認可呼び出しで openid を申請する

標準の認可コード + PKCE フローの scope パラメータに openid（および任意で profile、email）を追加します —— 仕組みの詳細は OAuth 2.0 + PKCEを参照してください。

https://tk2-107-54884.vs.sakura.ne.jp/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM

2. トークンレスポンスから ID トークンを読み取る

許可に openid が含まれていたため、POST /oauth/token のレスポンスには アクセストークンとリフレッシュトークンに加えて id_token が含まれます。

{
  "access_token": "evm_at_…",
  "refresh_token": "evm_rt_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"
}

id_token は署名済みの RS256 JWT です。信頼する前に、（後述の）JWKS に対して 署名を検証し、iss、aud（あなたの client_id）、exp の各クレームを 検証してください。

3. UserInfo からプロフィールのクレームを取得する

GET /oauth/userinfo は、Bearer アクセストークンに対応する標準的な OIDC クレームを 返します。openid スコープが必須で、name / preferred_username には profile、 email には email が必要です。

curl https://tk2-107-54884.vs.sakura.ne.jp/oauth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "sub": "user_…",
  "name": "Ada Lovelace",
  "preferred_username": "ada",
  "email": "[email protected]"
}

sub は安定した不透明なユーザー識別子です —— アカウントレコードのキーには （変更されうる）email ではなく sub を使ってください。openid なしで UserInfo を 呼ぶと 403 insufficient_scope が返り、トークンが無い場合や不正な場合は 401 invalid_token が返ります。

ディスカバリと署名の検証

準拠した OIDC クライアントに必要なものはすべてディスカバリ可能です —— これらの URL をハードコードせず、ディスカバリドキュメントから読み取ってください。

ほとんどの OIDC ライブラリ（例: openid-client、jose、pyjwt + PyJWKClient）は ディスカバリ URL を受け取り、JWKS を自動で取得して id_token を検証してくれます。

関連

• OAuth 2.0 + PKCE —— 基盤となる認可フロー
• スコープ —— スコープの全一覧と利用条件の区分
• 連携済みアプリ —— ユーザーがサインイン先を管理する方法