API 文档

UG 鉴权中心 v0.2.0 · 标准 REST API · 完整 OIDC Provider

Base URL: https://auth.ug666.topJWT RS256

公开 API

无需认证,所有客户端可直接调用。Base URL:https://auth.ug666.top

POST/api/auth/register

注册新用户,注册成功后发送验证邮件。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "YourStr0ngP@ss",
    "username": "alice"
  }'

响应示例

{
  "success": true,
  "data": {
    "userId": "clxxxxxxxxxxxxx",
    "message": "注册成功,请查收验证邮件"
  }
}
POST/api/auth/verify-email

验证邮箱,验证成功后返回 Access Token。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "clxxxxxxxxxxxxx",
    "code": "123456"
  }'

响应示例

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 900,
    "user": {
      "id": "clxxx",
      "email": "user@example.com",
      "username": "alice"
    }
  }
}
POST/api/auth/login

用户登录,返回 Access Token,同时设置 HttpOnly Cookie 存储 Refresh Token。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "YourStr0ngP@ss",
    "appId": "your_app_id"
  }'

响应示例

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 900,
    "user": {
      "id": "clxxx",
      "email": "user@example.com",
      "username": "alice"
    }
  }
}
POST/api/auth/refresh

刷新 Access Token,使用 Refresh Token Rotation,每次刷新都会换发新 RT。

refresh_token 通过 HttpOnly Cookie (rt) 自动传递,无需手动添加请求体。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/refresh \
  --cookie "rt=your_refresh_token"

响应示例

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 900
  }
}
POST/api/auth/logout

单设备登出,清除当前 Refresh Token。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/logout \
  -H "Authorization: Bearer <accessToken>"

响应示例

{
  "success": true,
  "message": "已登出"
}
POST/api/auth/logout-all

全设备登出,撤销该用户的所有 Refresh Token。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/logout-all \
  -H "Authorization: Bearer <accessToken>"

响应示例

{
  "success": true,
  "message": "已在所有设备登出"
}
POST/api/auth/forgot-password

发送密码重置邮件,无论邮箱是否存在均返回相同响应(防枚举)。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

响应示例

{
  "success": true,
  "message": "重置密码邮件已发送(如账号存在)"
}
POST/api/auth/reset-password

使用邮件中的 token 重置密码,token 一次性有效。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_token_from_email",
    "newPassword": "NewStr0ngP@ss"
  }'

响应示例

{
  "success": true,
  "message": "密码重置成功"
}

OIDC

标准 OpenID Connect 端点,兼容所有 OIDC 客户端库。

GET/api/oidc/authorize

授权端点,发起 Authorization Code Flow(支持 PKCE)。

请求示例 (curl)

# 通常由浏览器重定向,以下为参数示意
GET /api/oidc/authorize
  ?response_type=code
  &client_id=your_app_id
  &redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback
  &scope=openid%20profile%20email
  &state=random_state
  &code_challenge=S256_challenge
  &code_challenge_method=S256

响应示例

# 重定向到 redirect_uri,携带 code 参数
HTTP/1.1 302 Found
Location: https://yourapp.com/callback
  ?code=authorization_code
  &state=random_state
POST/api/oidc/token

Token 端点,使用授权码换取 Access Token / Refresh Token。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=authorization_code" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=your_app_id" \
  -d "code_verifier=pkce_verifier"

响应示例

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "rt_xxxxxxxxxxxxxxxx",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}
GET/api/oidc/userinfo

UserInfo 端点,使用 Access Token 获取用户信息。

请求示例 (curl)

curl https://auth.ug666.top/api/oidc/userinfo \
  -H "Authorization: Bearer <access_token>"

响应示例

{
  "sub": "clxxxxxxxxxxxxx",
  "email": "user@example.com",
  "email_verified": true,
  "name": "alice",
  "preferred_username": "alice"
}
POST/api/oidc/introspect

Token 自省端点,验证 token 是否有效(需要应用凭证)。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/oidc/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "your_app_id:your_app_secret" \
  -d "token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

响应示例

{
  "active": true,
  "sub": "clxxxxxxxxxxxxx",
  "scope": "openid profile email",
  "client_id": "your_app_id",
  "exp": 1714000000
}
POST/api/oidc/revoke

撤销 Token(access_token 或 refresh_token)。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/oidc/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "your_app_id:your_app_secret" \
  -d "token=rt_xxxxxxxxxxxxxxxx" \
  -d "token_type_hint=refresh_token"

响应示例

HTTP/1.1 200 OK
# 空响应体(RFC 7009 规范)
GET/api/oidc/end-session

单点登出端点,清除服务端 session 并重定向。

请求示例 (curl)

GET /api/oidc/end-session
  ?id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  &post_logout_redirect_uri=https%3A%2F%2Fyourapp.com
  &state=random_state

响应示例

# 重定向到 post_logout_redirect_uri
HTTP/1.1 302 Found
Location: https://yourapp.com?state=random_state

用户

需要 Authorization: Bearer <access_token>

GET/api/user/profile

查看当前用户个人信息。

请求示例 (curl)

curl https://auth.ug666.top/api/user/profile \
  -H "Authorization: Bearer <access_token>"

响应示例

{
  "success": true,
  "data": {
    "id": "clxxxxxxxxxxxxx",
    "email": "user@example.com",
    "username": "alice",
    "avatarUrl": "https://cdn.example.com/avatar.jpg"
  }
}
PATCH/api/user/profile

修改个人信息(username / avatarUrl 任选其一)。

请求示例 (curl)

curl -X PATCH https://auth.ug666.top/api/user/profile \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice_new",
    "avatarUrl": "https://cdn.example.com/new-avatar.jpg"
  }'

响应示例

{
  "success": true,
  "data": {
    "id": "clxxxxxxxxxxxxx",
    "email": "user@example.com",
    "username": "alice_new",
    "avatarUrl": "https://cdn.example.com/new-avatar.jpg"
  }
}
POST/api/user/change-password

修改密码,需提供当前密码作为二次验证。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/user/change-password \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "OldStr0ngP@ss",
    "newPassword": "NewStr0ngP@ss"
  }'

响应示例

{
  "success": true,
  "message": "密码修改成功"
}
GET/api/user/devices

查看当前用户已登录的设备列表。

请求示例 (curl)

curl https://auth.ug666.top/api/user/devices \
  -H "Authorization: Bearer <access_token>"

响应示例

{
  "success": true,
  "data": [
    {
      "id": "device_id_1",
      "deviceName": "Chrome on macOS",
      "ipAddress": "1.2.3.4",
      "lastActiveAt": "2026-04-12T08:00:00.000Z"
    }
  ]
}
DELETE/api/user/devices/:deviceId

移除指定设备的登录会话,强制该设备下线。

请求示例 (curl)

curl -X DELETE https://auth.ug666.top/api/user/devices/device_id_1 \
  -H "Authorization: Bearer <access_token>"

响应示例

{
  "success": true,
  "message": "设备已移除"
}

接入方式

不提供 SDK,也不需要在接入方复制我们的代码。业务后端二选一:调验签接口(最简单),或本地验签(少一次网络往返)。前端只用任意标准 OIDC 库。

POST/api/apps/verify-token

校验 access token 并返回用户与角色

用应用凭据(X-App-Id / X-App-Secret)调用;token 的 aud 必须等于该应用,返回 valid=false 表示无效、已撤销或用户已被封禁

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/apps/verify-token \
  -H 'content-type: application/json' \
  -H 'x-app-id: your_app_id' \
  -H 'x-app-secret: <app_secret>' \
  -d '{"accessToken":"<access_token>"}'

响应示例

{
  "success": true,
  "data": {
    "valid": true,
    "user": { "id": "u_xxx", "email": "a@b.com", "roles": ["admin"], "tokenVersion": 3 }
  }
}

本地验签要校验什么

  • 公钥从 /.well-known/jwks.json 取(按 kid 匹配),缓存但允许轮换
  • 算法固定 RS256,不要接受 none 或对称算法
  • iss = https://auth.ug666.top,aud = 你的 appId
  • exp / nbf 必须校验,容忍时钟偏移不超过 60 秒
  • aud 必须等于自己的 appId;不做本地校验时改为调验签接口(能感知撤销名单与封禁)

前端登录

用标准授权码 + PKCE 流程,任意 OIDC 客户端库都能接:authority 填 https://auth.ug666.top,client_id 填你的 appId,回调地址在应用的允许列表里配置。 不要在前端保存 client secret。

管理后台 API

供 UG Console 等管理端调用,全部位于 /api/v1/admin 下,使用平台管理员 Cookie 会话鉴权。未登录返回 401,越权返回 403。以下条目由路由文件生成,与实际实现一致。

应用与密钥

方法路径说明
GET/api/v1/admin/apps分页列表
POST/api/v1/admin/apps新建
DELETE/api/v1/admin/apps/:appId删除
GET/api/v1/admin/apps/:appId读取单条记录
PATCH/api/v1/admin/apps/:appId更新
GET/api/v1/admin/apps/:appId/admins读取单条记录
POST/api/v1/admin/apps/:appId/admins新建
DELETE/api/v1/admin/apps/:appId/admins/:userId删除
PATCH/api/v1/admin/apps/:appId/admins/:userId更新
GET/api/v1/admin/apps/:appId/members读取单条记录
POST/api/v1/admin/apps/:appId/members新建
PATCH/api/v1/admin/apps/:appId/members/:userId更新
GET/api/v1/admin/apps/:appId/permissions读取单条记录
POST/api/v1/admin/apps/:appId/permissions新建
DELETE/api/v1/admin/apps/:appId/permissions/:key删除
PATCH/api/v1/admin/apps/:appId/permissions/:key更新
POST/api/v1/admin/apps/:appId/regen-secret重置应用密钥
DELETE/api/v1/admin/apps/:appId/roles调整角色
GET/api/v1/admin/apps/:appId/roles读取角色
POST/api/v1/admin/apps/:appId/roles调整角色
GET/api/v1/admin/apps/:appId/roles/:roleName/permissions读取单条记录
GET/api/v1/admin/apps/:appId/secret读取应用密钥

审计日志

方法路径说明
GET/api/v1/admin/audit-logs分页列表
GET/api/v1/admin/audit-logs/export导出 CSV

管理员会话

方法路径说明
POST/api/v1/admin/auth/login管理员登录
POST/api/v1/admin/auth/logout管理员登出
GET/api/v1/admin/auth/me当前管理员

账号清理

方法路径说明
POST/api/v1/admin/cleanup-unverified新建

gateway

方法路径说明
DELETE/api/v1/admin/gateway/:service/:...path删除
GET/api/v1/admin/gateway/:service/:...path读取单条记录
PATCH/api/v1/admin/gateway/:service/:...path更新
POST/api/v1/admin/gateway/:service/:...path新建

邀请

方法路径说明
GET/api/v1/admin/invites分页列表
POST/api/v1/admin/invites新建
DELETE/api/v1/admin/invites/:id删除
PATCH/api/v1/admin/invites/:id更新

登录历史

方法路径说明
GET/api/v1/admin/login-history分页列表
GET/api/v1/admin/login-history/export导出 CSV

平台管理员

方法路径说明
GET/api/v1/admin/platform-admins分页列表
POST/api/v1/admin/platform-admins新建
DELETE/api/v1/admin/platform-admins/:id删除
PATCH/api/v1/admin/platform-admins/:id更新

会话

方法路径说明
DELETE/api/v1/admin/sessions删除
GET/api/v1/admin/sessions分页列表
DELETE/api/v1/admin/sessions/:sessionId删除

服务设置

方法路径说明
GET/api/v1/admin/settings分页列表
PATCH/api/v1/admin/settings更新
POST/api/v1/admin/settings/test-email发送测试邮件

平台用户

方法路径说明
GET/api/v1/admin/users分页列表
GET/api/v1/admin/users/:userId读取单条记录
POST/api/v1/admin/users/:userId/ban封禁用户
GET/api/v1/admin/users/:userId/devices设备列表
POST/api/v1/admin/users/:userId/force-logout强制下线
POST/api/v1/admin/users/:userId/reset-password重置密码
DELETE/api/v1/admin/users/:userId/roles调整角色
GET/api/v1/admin/users/:userId/roles读取角色
POST/api/v1/admin/users/:userId/roles调整角色
POST/api/v1/admin/users/:userId/unban解封用户
POST/api/v1/admin/users/create新建

Well-known

OIDC Discovery 和 JWKS 端点,无需认证,公开可访问。

GET/.well-known/openid-configuration

OIDC Discovery 文档,包含所有端点 URL 及支持的 scopes / grant types。

请求示例 (curl)

curl https://auth.ug666.top/.well-known/openid-configuration

响应示例

{
  "issuer": "https://auth.ug666.top",
  "authorization_endpoint": "https://auth.ug666.top/api/oidc/authorize",
  "token_endpoint": "https://auth.ug666.top/api/oidc/token",
  "userinfo_endpoint": "https://auth.ug666.top/api/oidc/userinfo",
  "jwks_uri": "https://auth.ug666.top/.well-known/jwks.json",
  "scopes_supported": ["openid", "profile", "email"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "id_token_signing_alg_values_supported": ["RS256"]
}
GET/.well-known/jwks.json

RSA 公钥 JWKS 端点,供第三方服务独立验签 JWT,无需回调。

请求示例 (curl)

curl https://auth.ug666.top/.well-known/jwks.json

响应示例

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-1",
      "use": "sig",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZptN9...",
      "e": "AQAB"
    }
  ]
}