第三方登录接入文档

REST 风格接口

接入流程

签名规则

信息接口使用 MD5 签名：将接口相关参数按 key 升序拼接为 k1=v1&k2=v2，末尾追加 &key=<appkey>，整体取 MD5（小写）。

以 userinfo 为例，参数为 appid / type / code：
原串 = appid=10001&code=xxxx&type=gitee&key=your_appkey
sign = md5(原串)
复制

1. 发起登录

POST /api/v1/oauth/login，请求体（JSON）：

{ "appid": "10001", "appkey": "your_appkey", "type": "gitee",
  "redirect_uri": "https://example.com/callback" }
复制

{ "code": 0, "message": "success",
  "data": { "url": "https://gitee.com/oauth/authorize?client_id=xxx&redirect_uri=xxx&state=xxx",
            "type": "gitee" } }
复制

用户授权完成后，平台 302 跳回 redirect_uri：

https://example.com/callback?type=gitee&code=xxxx
复制

2. 换取用户信息

POST /api/v1/oauth/userinfo，请求体（JSON）：

{ "appid": "10001", "code": "xxxx", "type": "gitee",
  "sign": "32 位 MD5 小写" }
复制

{ "code": 0, "message": "success",
  "data": { "type": "gitee", "openid": "123456", "unionid": "u_8888",
            "nickname": "张三", "avatar": "https://avatar.example.com/1.png",
            "email": "zhangsan@example.com", "gender": "男",
            "location": "广东深圳", "access_token": "xxxx", "ip": "1.2.3.4" } }
复制

3. 按 UID 查询用户

POST /api/v1/oauth/query，请求体（JSON）：

{ "appid": "10001", "type": "gitee", "social_uid": "123456",
  "sign": "32 位 MD5 小写" }
复制

{ "code": 0, "message": "success",
  "data": { "type": "gitee", "openid": "123456", "nickname": "张三",
            "avatar": "https://avatar.example.com/1.png",
            "location": "广东深圳", "ip": "1.2.3.4" } }
复制

4. 获取已启用渠道

GET /api/oauth/providers，公开接口，无需鉴权：

{ "code": 0, "message": "success",
  "data": [ { "name": "gitee", "display_name": "Gitee", "category": "social" } ] }
复制

错误码

标准 OAuth2 / OIDC 授权服务器

端点一览

接入流程

端点全部发布在 issuer（本站 HOST）根路径 下，与 OIDC Discovery 规范一致；旧前缀 /api/oauth2/* 仍作为兼容别名可用。

平台账号登录（IDP / CAS）

未指定 type 的授权页提供「使用 OauthGo 账号」登录：支持账号密码与 Passkey / WebAuthn 无密码登录。登录成功后平台直接为该账号签发授权码回跳目标站点，实现以平台账号为身份源的单点登录（SSO）。

1. 发起授权

应用须先配置「OAuth2/OIDC 回调地址」（完整 URL，按 scheme+host+path 匹配，忽略 query）。client_id / redirect_uri 兼容 appid、redirect_url 等非标准命名。type 可选：渠道名（provider name，如 wechat / gitee / qq / oauth2）。

https://your-host/authorize?response_type=code&client_id=10001&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=openid%20profile&state=abc123
复制

2. 授权成功回跳

https://example.com/oauth/callback?code=xxxx&state=abc123
复制

3. 换取令牌

客户端认证支持表单（client_id + client_secret）或 HTTP Basic；应用在「应用管理」中开启「签发刷新令牌」时返回 refresh_token。

curl -X POST https://your-host/token \
  -d "grant_type=authorization_code" \
  -d "code=xxxx" \
  -d "client_id=10001" \
  -d "client_secret=your_appkey" \
  -d "redirect_uri=https://example.com/oauth/callback"
复制

{ "access_token": "xxxx", "token_type": "Bearer", "expires_in": 7200,
  "refresh_token": "xxxx", "scope": "openid profile",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im9hdXRobmctcnNhLTEifQ.xxx.yyy" }
复制

4. 获取用户信息

curl https://your-host/userinfo -H "Authorization: Bearer ACCESS_TOKEN"
复制

{ "sub": "12", "name": "张三", "preferred_username": "zhangsan",
  "picture": "https://avatar.example.com/1.png", "email": "zhangsan@example.com",
  "scope": "openid profile",
  "accounts": [ { "provider": "wechat", "openid": "oXXXX", "unionid": "uXXXX", "nickname": "张三" } ] }
复制

sub 为该平台稳定用户标识；accounts 列出其绑定的第三方账号（聚合场景可直接取 openid / unionid）。

安全特性