SSO 统一身份认证中心 — 接入文档

概述

本文档面向第三方应用开发者，介绍如何接入 SSO 统一身份认证中心，实现 OAuth 2.0 授权登录、Token 换取用户信息以及 API 直连登录。

认证中心地址: http://auth.knownil.com

---

1. OAuth 2.0 授权登录

1.1 授权流程

用户 → 第三方应用 → SSO 授权页 → 用户登录/授权 → 回调第三方应用（携带 code）
→ 第三方应用后端 → POST /oauth/token（code 换 token）→ 返回 access_token
→ 第三方应用后端 → GET /api/userinfo（token 换用户信息）→ 返回用户数据

1.2 构建授权 URL

端点: GET /oauth/authorize

请求参数

参数	类型	必填	说明
app_id	string	是	应用 ID，由 SSO 管理员分配
redirect_uri	string	是	授权成功后的回调地址，必须与应用注册时填写的回调地址匹配
state	string	推荐	防 CSRF 随机字符串，回调时会原样返回
scope	string	否	授权范围，默认为 basic。多个 scope 用空格分隔

完整示例

http://auth.knownil.com/oauth/authorize?app_id=myapp&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&state=abc123&scope=basic

1.3 处理回调

用户授权后，SSO 会将浏览器重定向到 redirect_uri，并携带以下参数：

参数	说明
code	授权码，用于换取 access_token，一次性使用，有效期默认为 10 分钟
state	原样返回的 state 值，务必验证以防 CSRF 攻击
app_id	应用 ID

回调 URL 示例

https://example.com/callback?code=a1b2c3d4e5f6&state=abc123&app_id=myapp

---

2. 授权码换取 Token

端点: POST /oauth/token

请求方式

POST http://auth.knownil.com/oauth/token
Content-Type: application/x-www-form-urlencoded

请求参数

参数	类型	必填	说明
grant_type	string	是	固定值 authorization_code
code	string	是	上一步获取的授权码
app_id	string	是	应用 ID
app_secret	string	是	应用密钥
redirect_uri	string	是	必须与获取授权码时的 redirect_uri 一致

成功响应 (200)

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "rT_abc123def456...",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_expires_in": 604800
}

字段	类型	说明
access_token	string	JWT 格式的访问令牌，用于换取用户信息
refresh_token	string	刷新令牌，用于在 access_token 过期后重新获取
token_type	string	令牌类型，固定为 bearer
expires_in	int	access_token 有效期（秒），默认 7200（2 小时）
refresh_expires_in	int	refresh_token 有效期（秒），默认 604800（7 天）

错误响应

{
    "code": 400,
    "msg": "授权码已过期"
}

---

3. Token 换取用户信息

端点: GET /api/userinfo 或 POST /api/userinfo

请求方式一：URL 参数

GET http://auth.knownil.com/api/userinfo?access_token=eyJhbGciOiJIUzI1NiIs...

请求方式二：Authorization 头

GET http://auth.knownil.com/api/userinfo
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

成功响应 (200)

{
    "code": 200,
    "user": {
        "id": 1,
        "email": "user@example.com",
        "phone": "13800138000",
        "username": "username",
        "avatar": "https://example.com/avatar.png",
        "kn_id": 1,
        "auth_id": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
    }
}

字段说明

字段	类型	说明
id	int	用户在 SSO 系统中的唯一标识
username	string	用户名
email	string	邮箱地址
phone	string	手机号
avatar	string	头像 URL
kn_id	int	用户在数据库中的原始 ID（等于 id）
auth_id	string	平台签名 ID，计算公式: HMAC-SHA256(id + app_id + app_secret, secret_key)，可用于服务端验签

auth_id 验签

auth_id 由以下算法生成：

auth_id = HMAC-SHA256(uid + app_id + app_secret, sso_secret_key)

• uid: 用户 ID
• app_id: 当前应用 ID
• app_secret: 当前应用密钥
• sso_secret_key: SSO 系统的 secret_key（config/sso.php 中配置）

第三方应用可在自己的服务端用相同的算法和参数计算 auth_id，与 SSO 返回的 auth_id 对比，以二次确认用户身份真实性，防止中间人篡改。

错误响应

{
    "code": 401,
    "msg": "Token 无效或已过期"
}

---

4. 刷新 Token

端点: POST /oauth/token

access_token 过期后，可使用 refresh_token 刷新。

请求参数

参数	类型	必填	说明
grant_type	string	是	固定值 refresh_token
refresh_token	string	是	之前获取的 refresh_token
app_id	string	是	应用 ID
app_secret	string	是	应用密钥

成功响应

与第 2 节"授权码换取 Token"的响应格式一致，返回新的 access_token 和 refresh_token。

---

5. 验证 Token 有效性（轻量接口）

端点: GET /api/check-token

只验证 Token 是否有效，不返回完整用户信息。

请求示例

GET http://auth.knownil.com/api/check-token?access_token=xxx
Authorization: Bearer xxx

成功响应 (200)

{
    "code": 200,
    "valid": true,
    "user_id": 1
}

失败响应

{
    "code": 401,
    "valid": false,
    "msg": "Token 无效或已过期"
}

---

6. API 直连登录

允许第三方应用直接传递用户凭据获取 Token，无需经过浏览器授权流程。

端点: POST /api/login

请求方式

POST http://auth.knownil.com/api/login
Content-Type: application/json

请求参数

参数	类型	必填	说明
app_id	string	是	应用 ID
app_secret	string	是	应用密钥
account	string	是	登录账号，支持用户名 / 邮箱 / 手机号
password	string	是	用户密码
scope	string	否	授权范围，默认 basic

请求示例

{
    "app_id": "myapp",
    "app_secret": "myapp_secret_xxx",
    "account": "user@example.com",
    "password": "user_password"
}

成功响应 (200)

{
    "code": 0,
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh_token": "rT_xxx...",
        "token_type": "bearer",
        "expires_in": 7200,
        "refresh_expires_in": 604800,
        "user": {
            "id": 1,
            "username": "username",
            "email": "user@example.com",
            "phone": "13800138000",
            "avatar": "https://example.com/avatar.png",
            "kn_id": 1,
            "auth_id": "a1b2c3d4e5f67890..."
        }
    }
}

错误响应

{
    "code": 400,
    "msg": "账号或密码错误"
}

---

7. 撤销 Token

端点: POST /api/revoke

用户退出登录时，建议撤销已颁发的 Token。

请求参数

参数	类型	必填	说明
access_token	string	是	要撤销的 access_token

---

8. 错误码参考

HTTP 状态码	code	说明
400	400	请求参数错误
401	401	Token 无效、过期或已被撤销
404	404	用户不存在

---

9. 最佳实践

1. state 参数: 务必使用随机生成的 state 值，并在回调时验证，防止 CSRF 攻击。
2. app_secret 保密: app_secret 仅在后端使用，绝对不能泄露到前端代码或客户端。
3. redirect_uri 白名单: 确保回调地址与应用注册时填写的一致。
4. Token 安全存储: access_token 和 refresh_token 应安全存储，建议使用 HTTPS 传输。
5. auth_id 二次验签: 获取用户信息后，建议在自己的服务端对 auth_id 做二次验签，确保数据未被篡改。