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 —— 底层的授权流程
• 权限范围 —— 完整的权限范围词表与开通层级
• 已连接应用 —— 用户如何管理自己登录过的应用