统一认证平台 - 简易认证 (Simple Auth) 集成指南

1. 概述

本指南适用于需要使用自定义登录页面（而非跳转到认证中心标准页面），并通过后端 API 直接进行用户认证的场景。

Base URL: http://localhost:8000/api/v1/simple (开发环境)

2. 核心流程

用户输入: 用户在客户端输入账号密码。
签名: 客户端/后端生成签名 (Sign)。
登录: POST /login (账号+密码+签名) -> 获取 Ticket。
验证: POST /validate (Ticket+签名) -> 获取用户信息。

3. 安全警告

App Secret 严禁泄露给前端浏览器。
建议所有涉及 Secret 的签名计算都在后端完成。

4. 签名算法 (Signature)

所有接口（除部分公开接口外）都需要校验签名。

步骤:

准备参数: 收集所有请求参数（排除 sign 本身）。
排序: 按照参数名（key）的 ASCII 码从小到大排序。
拼接: 将排序后的参数拼接成 key1=value1&key2=value2... 格式。
计算 HMAC: 使用 App Secret 作为密钥，对拼接字符串进行 HMAC-SHA256 计算。
Hex 编码: 将结果转换为十六进制字符串。

Python 示例

import hmac
import hashlib

def generate_signature(secret: str, params: dict) -> str:
    data = {k: v for k, v in params.items() if k != "sign" and v is not None}
    sorted_keys = sorted(data.keys())
    query_string = "&".join([f"{k}={data[k]}" for k in sorted_keys])
    signature = hmac.new(
        secret.encode('utf-8'),
        query_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return signature

5. 接口定义

5.1 密码登录 (Login)

获取临时票据 (Ticket)。

URL: POST /login
Content-Type: application/json

Request Body: | Field | Type | Required | Description | |---|---|---|---| | app_id | string | Yes | 应用 ID | | identifier | string | Yes | 用户标识（手机号、用户名或邮箱） | | password | string | Yes | 明文密码 | | timestamp | int | Yes | 当前时间戳 (秒) | | sign | string | Yes | 签名 |

Response (200):

{
  "ticket": "TICKET-7f8e9d0a-..." 
}

5.2 验证票据 (Validate)

解析票据获取用户信息。

URL: POST /validate
Content-Type: application/json

Request Body: | Field | Type | Required | Description | |---|---|---|---| | app_id | string | Yes | 应用 ID | | ticket | string | Yes | 上一步获取的票据 | | timestamp | int | Yes | 当前时间戳 | | sign | string | Yes | 签名 (参数变化需重新计算) |