YOS-Pass 统一身份认证

关于 YOS-Pass

YOS-Pass 是由 广东思丞技术支持服务中心 研发的新一代统一身份认证平台。 它基于 OAuth 2.0 思想，采用二维码扫码 + JWT Token 签名验证机制，为 Web、App、小程序等多端应用提供安全、快捷的登录服务。

通过 YOS-Pass，你的用户无需记住账号密码，只需使用 YOS 万象 IOA App 扫描二维码，即可一键完成登录， 同时你的应用无需存储用户密码，大幅降低安全风险。

已接入 支持管理员 支持第三方应用 签名防篡改

计费说明

• 扣费规则：仅在 complete_login() 生成 JWT Token 时扣费，扫码后用户取消不扣费。
• 配额耗尽：当 used_quota >= total_quota 时，新登录请求返回错误码 3002（可用余额不足），需联系管理员充值。
• 费率限制：每个应用独立配置每分钟/每日请求上限，超出返回错误码 3001（速率限制）。

接入流程

第三方应用接入 YOS-Pass 只需以下 5 个步骤：

1. 注册应用：在管理员后台创建接入方，获得 app_key 和 app_secret。
2. 发起登录：你的服务端使用 app_key 和 app_secret 生成签名，调用 api/start_login.php，获取二维码数据。
3. 展示 & 扫码：将二维码展示给用户，用户使用 YOS 万象 IOA App 扫描。
4. 获取令牌：前端轮询 api/session_status.php，授权成功后获得 access_token（JWT 格式）。
5. 验证令牌：你的服务端对 access_token 进行 JWT 签名验证，通过后完成登录。

推荐 如果你的 App 或网站不想自行实现轮询，可以使用我们提供的 通用登录页（login.php），只需跳转链接即可完成全流程。

API 接口文档

Content-Type: application/json
X-Request-Signature: {HMAC-SHA256}

{
  "app_key": "your_app_key",
  "app_secret": "your_app_secret",
  "timestamp": 1234567890,
  "nonce": "random_string"
}

{
  "success": true,
  "error_code": 0,
  "session_id": "64位hex",
  "qr_data": "base64编码的JSON",
  "expires_in": 150
}

{
  "success": false,
  "error_code": 4004,
  "message": "域名不在白名单内"
}

{
  "status": "pending",
  "success": true,
  "message": "等待扫码授权"
}

{
  "status": "authorized",
  "success": true,
  "access_token": "jwt_token"
}

{
  "status": "expired",
  "error_code": 1002,
  "message": "二维码已过期"
}

{
  "session_id": "xxx",
  "signature": "HMAC签名",
  "timestamp": 1234567890
}

{
  "success": true,
  "error_code": 0,
  "message": "授权成功",
  "access_token": "token",
  "type": "admin" 或 "app"
}

密钥体系说明

整个接入流程涉及 两类密钥，各自用途不同，请勿混淆：

关键 ③ JWT 签发和④ JWT 验签使用同一把密钥（你自己的 app_secret），而非系统全局密钥。 每个 App 的密钥独立，互不干扰——你的 app_secret 只签你自己的 Token。

请求时序：谁发什么、用什么密钥

┌──────────────┐                ┌──────────────┐                ┌──────────────┐
│   youquan    │                │   YOS-Pass   │                │  YOS IOA App │
│  (第三方App)  │                │   (认证服务)  │                │   (扫码端)    │
└──────┬───────┘                └──────┬───────┘                └──────┬───────┘
       │                               │                               │
       │ ① POST start_login             │                               │
       │   签名: YOS_APP_SECRET         │                               │
       │   Body: {app_key, ts, nonce}   │                               │
       ├──────────────────────────────►│                               │
       │                               │                               │
       │ ◄── {session_id, qr_data}     │                               │
       │                               │                               │
       │ ② 展示二维码                    │                               │
       │                               │         ③ POST authorize      │
       │                               │ 签名: app_secret               │
       │                               │ Body: {session_id, sig, ts}   │
       │                               │◄──────────────────────────────┤
       │                               │                               │
       │                               │ DB: status=1 ────────────────►│
       │                               │                               │
       │ ④ GET session_status           │                               │
       │   ?session_id=xxx             │                               │
       ├──────────────────────────────►│                               │
       │                               │ complete_login()              │
       │                               │ JWT 签名: app_secret          │
       │                               │                               │
       │ ◄── {access_token: JWT}       │                               │
       │                               │                               │
       │ ⑤ 本地 verifyJwt()             │                               │
       │   密钥: YOS_APP_SECRET         │                               │
       │   → 验签通过，登录成功           │                               │

Token 格式与验证

扫码授权成功后返回的 access_token 是一个 JWT（JSON Web Token）， 你的服务端必须对该 Token 进行签名验证后才能信任其中的用户身份， 否则相当于未做任何鉴权。以下是完整规范：

4.1 Token 结构

Token 由三段组成，以 "." 分隔：header.payload.signature

// Header（固定）
{
  "alg": "HS256",
  "typ": "JWT"
}

// Payload 示例
{
  "user_id": 1,
  "exp": 1783810118,
  "iat": 1783802918
}

4.2 签名密钥

重要 JWT 签名密钥是你自己的 app_secret。 YOS-Pass 在 complete_login() 中会从数据库查出你注册的 app_secret 来签发 Token。 你需要在服务端配置 YOS_APP_SECRET 为与 app_secret 相同的值来验证 Token。 不同 App 的密钥独立，天然隔离，一个 App 的 Token 无法被另一个 App 用来验签。

4.3 编码方式

注意 YOS-Pass 的 JWT 使用 标准 Base64 编码 （PHP 的 base64_encode / base64_decode）， 不是 JWT 规范中的 Base64URL 编码。 这意味着编码结果中可能包含 +、/、= 字符。

4.4 验证流程

1. 以 "." 分割 Token，得到三部分：Header、Payload、Signature
2. 对 Header 和 Payload 分别做标准 Base64 解码，得到 JSON 原始数据
3. 校验 exp 是否已过期（建议额外加上 ±90 秒的时钟偏差容忍）
4. 使用 YOS-Pass 统一密钥对 "Header.Payload"（拼接时使用原始 Base64 编码值，不含 "." 且不做二次解码）做 HMAC-SHA256 签名
5. 将计算结果与 Token 中的 Signature 做 Base64 解码后按原始字节比对
6. 验签通过后，从 Payload 中取出 user_id 完成登录

4.5 PHP 验证代码

/**
 * 验证 YOS-Pass JWT Token
 * @param string $token   完整的 JWT Token 字符串
 * @param string $secret  YOS-Pass 统一签名密钥（从管理员处获取）
 * @return array|false    验签成功返回 payload 数组，失败返回 false
 */
function verifyYosToken($token, $secret) {
    $parts = explode('.', $token);
    if (count($parts) !== 3) {
        return false;  // Token 格式错误
    }

    list($headerB64, $payloadB64, $signatureB64) = $parts;

    // 使用标准 base64_decode（非 base64url）
    $header    = json_decode(base64_decode($headerB64), true);
    $payload   = json_decode(base64_decode($payloadB64), true);
    $signature = base64_decode($signatureB64);

    if (!$header || !$payload || !$signature) {
        return false;  // 解码失败
    }

    // 校验算法
    if ($header['alg'] !== 'HS256') {
        return false;
    }

    // 校验过期时间（±90 秒时钟偏差容忍）
    if (isset($payload['exp']) && time() - 90 > $payload['exp']) {
        return false;  // Token 已过期
    }

    // 计算签名：签名原文为 "headerB64.payloadB64"（原始 Base64 字符串，不做二次编码）
    $expectedSig = hash_hmac('sha256', $headerB64 . '.' . $payloadB64, $secret, true);

    // 二进制安全比对
    if (!hash_equals($expectedSig, $signature)) {
        return false;  // 签名不匹配
    }

    return $payload;
}

// 使用示例：
// $payload = verifyYosToken($_POST['access_token'], $jwtSecret);
// if ($payload) {
//     $_SESSION['user_id'] = $payload['user_id'];
// } else {
//     die('Token 验证失败');
// }

4.6 常见错误

• 签名不匹配：验签时用的密钥与签发密钥不一致——JWT 用你自己的 app_secret 签发，验签时必须用同一把密钥（即 YOS_APP_SECRET = app_secret）。
• 使用 base64url_decode 验签失败：YOS-Pass 使用标准 Base64（PHP base64_encode），不是 JWT 规范的 Base64URL（-/_）。
• 签名原文错误：签名计算原文是"原始 Base64 字符串 + '.' + 原始 Base64 字符串"（即 Token 前两段原样），不是解码后的 JSON。
• 忘记验签直接信任 Token：严重安全漏洞，攻击者可伪造任意 Token，必须在服务端验签后再信任。

请求签名机制

所有 POST 请求（除授权接口外）必须在请求头 X-Request-Signature 中携带 HMAC-SHA256 签名， 签名原文为 整个请求体（raw body），密钥为 app_secret，签名结果经 Base64 编码。

// PHP 服务端签名示例
$secret = 'your_app_secret';
$body = file_get_contents('php://input');
$signature = base64_encode(hash_hmac('sha256', $body, $secret, true));

// JavaScript（浏览器）签名示例（仅用于测试）
const signature = CryptoJS.HmacSHA256(body, appSecret).toString(CryptoJS.enc.Base64);

错误码对照表

所有接口返回的错误码定义如下，便于您快速定位问题。

快速开始（PHP）

// ===== 配置 =====
$jwtSecret  = 'YOS-Pass 统一签名密钥';  // 从管理员处获取
$appKey     = 'your_app_key';
$appSecret  = 'your_app_secret';

// ===== 1. 发起登录，获取二维码 =====
$apiUrl = 'https://auth.ycceo.com/YOS-Pass/api/start_login.php';
$data = [
    'app_key'    => $appKey,
    'app_secret' => $appSecret,
    'timestamp'  => time(),
    'nonce'      => bin2hex(random_bytes(8))
];
$body = json_encode($data);
$signature = base64_encode(hash_hmac('sha256', $body, $appSecret, true));

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Request-Signature: ' . $signature
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    $sessionId = $result['session_id'];
    $qrData = base64_decode($result['qr_data']);  // 用于生成二维码图片
    // 将 $qrData 或 $sessionId 传给前端
}

// ===== 2. 前端轮询（建议每 2 秒一次，超时 150 秒）=====
// GET https://auth.ycceo.com/YOS-Pass/api/session_status.php?session_id=xxx
// 当 status === 'authorized' 时，将 access_token 用 POST 提交给你的服务端

// ===== 3. 服务端验证 Token（你的 login callback）=====
// 收到前端传来的 access_token 后：
$token   = $_POST['access_token'];
$payload = verifyYosToken($token, $jwtSecret);  // verifyYosToken 见上文第 4 节

if ($payload) {
    $_SESSION['user_id'] = $payload['user_id'];
    // 登录成功，跳转或返回
} else {
    http_response_code(401);
    die(json_encode(['error' => 'Token 无效或已过期']));
}

安全建议

• JWT 密钥保密：YOS-Pass 统一签名密钥必须存储在服务端，禁止暴露给前端或客户端。
• app_secret 保密：app_secret 必须存储在服务端，禁止暴露给前端或客户端。
• 必须验证 Token：收到 access_token 后必须在服务端验签，不能仅凭 Token 存在就信任登录。
• 时间窗口：服务器校验 timestamp 与当前时间差值，建议 ±90 秒，防止重放攻击。
• Token 过期：务必校验 exp 字段，拒绝使用已过期的 Token。
• 域名白名单：在后台配置允许的回调域名，避免令牌被非法使用。
• 定期轮换：建议定期更换 app_secret 和 JWT 签名密钥（如每季度），降低泄露风险。
• HTTPS：务必使用 HTTPS 加密传输，防止中间人攻击。

技术支持

如有接入问题或定制需求，请联系我们的技术支持团队：

• 邮箱：chenchen@ycceo.fun
• 平台官网：https://auth.ycceo.com/YOS-Pass/
• 主站官网：https://ycceo.com
• 广东思丞技术支持服务中心 · 统一身份认证事业部