YOS-Pass 统一身份认证

架构总览

整个认证系统分为两层：YOS-Pass 站点（auth.ycceo.com/YOS-Pass/，负责托管登记、门禁卡与钥匙管理、接入代码生成、文档）与 qrcode 认证服务（负责二维码生成、会话管理、一键登录、JWT 签发与验签）。接入方通过 app_key（门禁卡，公开）+ app_secret（钥匙，仅服务端）与两个服务交互。

接入方式

• 方式 A · 前端一键登录：前端只带门禁卡 app_key 请求 https://auth.ycceo.com/qrcode/yoslogin.php 发起会话，服务端托管钥匙代签并生成二维码；前端展示二维码、每 2 秒轮询 https://auth.ycceo.com/YOS-Pass/api/session_status.php，授权成功后携带 access_token 跳转。钥匙永不接触前端。
• 方式 B · PHP 服务端完整接入：服务端用 app_key + app_secret 对请求体做 HMAC-SHA256 签名，带 X-Request-Signature 头调用 https://auth.ycceo.com/YOS-Pass/api/start_login.php；前端轮询状态；服务端对 access_token 做 JWT 验签（强制 exp）。

二维码生成与一键登录接口

渲染二维码图片，返回 PNG 图片流。二维码内容由服务端按 app_key + 会话参数拼接生成，7 天过期机制由 QR_EXPIRY_DAYS 配置控制。

一键登录入口（方式 A）：前端提交门禁卡 app_key 及回调参数，服务端用托管钥匙代签、创建会话并返回二维码内容 / 会话 ID（响应带 qr_url 与 session_id）。前端无需也禁止携带 app_secret。

方式 B：服务端用 app_key + app_secret 做 HMAC-SHA256 签名，携带 X-Request-Signature 请求头调用，创建会话并返回二维码内容 / 会话 ID。

查询会话状态：pending（等待扫码）/ success（授权成功，返回 access_token）/ expired（过期）。前端每 2 秒轮询一次。

签名与验签规范

• 请求体字符串为 原始 JSON body 的 UTF-8 字节。
• HMAC-SHA256 的密钥 = 你的 app_secret。
• 签名结果 Base64 后放入 X-Request-Signature 请求头。
• JWT 验签：标准 base64 拆分 header.payload.signature；签名原文为 headerB64.payloadB64（中间一个点）；签名密钥 = 你的 app_secret；验签后强制校验 exp，缺失 / 过期一律拒绝。

JWT 结构说明

header.payload.signature
// header（头部）：
{"alg":"HS256","typ":"JWT"}
// payload（载荷）关键字段：
//   exp  过期时间戳（秒，必校验）
//   iat  签发时间戳
//   app_key  门禁卡标识
//   uid / openid / user_info  用户标识（授权成功时写入）
// signature = HMAC_SHA256( base64(header)+"."+base64(payload), app_secret )

错误码对照表（20 项）

安全建议（必读）

• app_secret 只允许存在于服务端，严禁出现在前端页面、源码、App 或日志里。
• 验签必须用 verifyYosToken() 等标准库，强制校验 exp，缺失 exp 的 Token 一律拒绝，防止"永恒 Token"。
• 所有接口建议启用 HTTPS；校验 CURLOPT_SSL_VERIFYPEER = true。
• 为敏感操作（删日志、重生成 app_secret、删接入方、删敏感配置）保留二次扫码授权：调用外部 https://auth.ycceo.com/qrcode/api.php 生成二维码，由 YOS IOA App 扫码授权，不能自签 JWT 绕过。
• 接入方页面遵循零浏览器储存约束：不使用 localStorage / sessionStorage / cookie 保存敏感信息，导出走一次性 Blob URL。
• 定期轮换 app_secret；发现泄露立即重新生成并下线旧密钥。