唯璐通行证开放 API

概述

唯璐通行证扫码登录基于 OAuth 2.0 协议中的 Authorization Code 授权模式构建。用户无需向第三方应用提供密码，通过唯璐通行证直接授权即可完成登录。

适用场景：PC 网站扫码登录、移动端浏览器授权、第三方应用集成。

授权流程

完整授权流程分三步：

1. 用户访问第三方应用 → 应用请求授权 → 用户扫码确认
2. 第三方应用使用 Code 换取 Access Token
3. 第三方应用使用 Access Token 获取用户基本信息

• 用户 在第三方应用中点击"唯璐通行证登录"
• 应用 将用户重定向至唯璐通行证授权页
• 用户 扫码确认后，平台发出一次性授权 Code
• 应用 接收 Code，通过后端接口换取 Access Token
• 应用 使用 Access Token 调用用户信息接口

第一步：请求授权 CODE

第三方应用将用户引导至唯璐通行证授权页。用户确认后返回一次性授权票据 code。

授权请求 URL

请求参数

请求示例

https://sso.velu.cc/oauth/authorize?client_id=cloud_velu_cc&redirect_uri=https%3A%2F%2Fcloud.velu.cc%2Fsso-callback&response_type=code&scope=snsapi_login&state=3d6be0a4035d839573b04816624a415e

返回说明

用户确认授权后，重定向到 redirect_uri 并附带参数：

redirect_uri?code=CODE&state=STATE

第二步：换取 Access Token

第三方应用收到 code 后，通过服务器端接口换取 Access Token。严禁在客户端代码中暴露 AppSecret。

接口地址

请求参数

返回数据

{
    "access_token": "ACCESS_TOKEN_STRING",
    "expires_in": 7200,
    "refresh_token": "REFRESH_TOKEN_STRING",
    "open_id": "USER_OPEN_ID",
    "scope": "snsapi_login"
}

PHP 实现示例

function exchangeToken($code, $state) {
    // 1. 校验 state 防止 CSRF
    if ($state !== $_SESSION['oauth_state']) {
        throw new Exception('state 不匹配，请求被拒绝');
    }
    
    $url = 'https://sso.velu.cc/oauth/token';
    $data = [
        'grant_type'    => 'authorization_code',
        'client_id'     => 'cloud_velu_cc',
        'client_secret' => APP_SECRET,
        'code'          => $code,
        'redirect_uri'  => 'https://cloud.velu.cc/sso-callback',
    ];
    
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($data),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_TIMEOUT => 10,
    ]);
    $resp = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($resp, true);
}

第三步：获取用户信息

接口地址

请求参数

返回数据

{
    "open_id": "USER_OPEN_ID",
    "nickname": "用户昵称",
    "avatar": "https://...",
    "real_name_status": "verified",
    "has_real_name": true,
    "phone_masked": "138****8000"
}

加密算法

AES-256-CBC 数据加密

敏感数据传输使用 AES-256-CBC 加密。密钥由开放平台与应用协商约定。

加密模式：AES-256-CBC
密钥长度：256 bit
初始向量：16 字节随机数（每次不同）
填充方式：PKCS7
编码方式：Base64

PHP 加解密示例

function encryptData($plaintext, $key) {
    $iv = openssl_random_pseudo_bytes(16);
    $encrypted = openssl_encrypt(
        $plaintext, 'aes-256-cbc', $key,
        OPENSSL_RAW_DATA, $iv
    );
    return base64_encode($iv . $encrypted);
}

function decryptData($ciphertext, $key) {
    $data = base64_decode($ciphertext);
    $iv = substr($data, 0, 16);
    $encrypted = substr($data, 16);
    return openssl_decrypt(
        $encrypted, 'aes-256-cbc', $key,
        OPENSSL_RAW_DATA, $iv
    );
}

哈希算法

• 消息摘要：SHA-256
• HMAC 签名：HMAC-SHA256
• 密码存储：bcrypt（10 轮）

签名机制

部分敏感接口要求携带签名（Signature）验证请求来源合法性。

签名生成步骤

1. 请求参数按名称升序排序
2. 拼接为 key=value&... 格式（不含签名字段）
3. 末尾拼接 &key=AppSecret
4. HMAC-SHA256 计算摘要
5. 转换为十六进制小写字符串

PHP 签名示例

function generateSignature($params, $secret) {
    unset($params['signature']);
    ksort($params);
    
    $pairs = [];
    foreach ($params as $k => $v) {
        $pairs[] = $k . '=' . $v;
    }
    $str = implode('&', $pairs);
    $str .= '&key=' . $secret;
    
    return strtolower(hash_hmac('sha256', $str, $secret));
}

CSRF 防护（State 参数）

每个授权请求须携带 state 参数防 CSRF 攻击。

推荐实现

// 生成 state
$state = bin2hex(random_bytes(16));
$_SESSION['oauth_state'] = $state;

// 构建授权 URL
$authorizeUrl = 'https://sso.velu.cc/oauth/authorize?' . http_build_query([
    'client_id'     => 'cloud_velu_cc',
    'redirect_uri'  => 'https://cloud.velu.cc/sso-callback',
    'response_type' => 'code',
    'scope'         => 'snsapi_login',
    'state'         => $state,
]);

// 回调校验
if ($_GET['state'] !== $_SESSION['oauth_state']) {
    die('CSRF 攻击已拦截');
}

参数对照表

错误码