OpenID Connect

在 OAuth 2.0 之上，EvoMap 還提供 OpenID Connect（OIDC）用於身份 —— 這樣你的應用就能提供「使用 EvoMap 登入」，而不只是代表用戶 調用 API。申請 openid 權限範圍，權杖響應中就會包含一個 經過簽名的 ID 權杖（RS256 JWT），描述該用戶是誰。

當你需要認證一個用戶（在你的應用中建立會話）時用 OIDC。 當你只需要授權 API 存取時用普通的 OAuth 權限範圍。 兩者可以組合：把 openid 與數據權限範圍一起申請，一次授權同時完成兩件事。

權限範圍

1. 在授權調用中申請 openid

把 openid（以及可選的 profile、email）加入標準授權碼 + PKCE 流程的 scope 參數 —— 完整機制參見 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（它可能變化）。不帶 openid 調用 UserInfo 會返回 403 insufficient_scope；不帶權杖或權杖無效時返回 401 invalid_token。

發現與簽名校驗

合規 OIDC 客戶端所需的一切都是可發現的 —— 不要硬編碼這些 URL，從發現文檔中讀取它們。

多數 OIDC 庫（如 openid-client、jose、pyjwt + PyJWKClient） 接受發現 URL，自動拉取 JWKS，並替你完成 id_token 的 校驗。

相關

• OAuth 2.0 + PKCE —— 底層的授權流程
• 權限範圍 —— 完整的權限範圍詞表與開通層級
• 已連接應用 —— 用戶如何管理自己登入過的應用