金牛ID OAuth 开发文档

5分钟快速接入（傻瓜式教程）

本教程将带你从零开始，一步步完成金牛ID登录的接入。每个步骤都有完整的代码，直接复制就能用。

www.yourwebsite.com
app.yourwebsite.com

127.0.0.1:8080
192.168.1.100:3000
10.0.0.5:5000

<!-- HTML: 金牛ID登录按钮 -->
<a href="https://id.jnqj.net/oauth/authorize?response_type=code&client_id=YOUR_API_KEY&redirect_uri=https%3A%2F%2Fwww.yourwebsite.com%2Fcallback.php&state=随机字符串&scope=basic profile" 
   style="display:inline-block;background:linear-gradient(135deg,#C2B59B,#8B7355);color:#fff;padding:12px 32px;border-radius:8px;text-decoration:none;font-size:16px;">
   🔑 金牛ID登录</a>

// PHP 生成 state$state = bin2hex(random_bytes(16)); // 生成32位随机字符串$_SESSION['oauth_state'] = $state;  // 存到session里，后面验证用
// Python 生成 stateimport secrets, session
state = secrets.token_hex(16)
session['oauth_state'] = state

// Node.js 生成 stateconst crypto = require('crypto');
const state = crypto.randomBytes(16).toString('hex');
req.session.oauthState = state;

<?php
// callback.php - 金牛ID登录回调处理
session_start();

// ====== 配置（换成你自己的） ======
$API_KEY    = 'YOUR_API_KEY';        // 你的API Key$API_SECRET = 'YOUR_API_SECRET';     // 你的API Secret$REDIRECT_URI = 'https://www.yourwebsite.com/callback.php'; // 回调地址（必须和白名单一致）// =================================

// 1. 检查是否有错误（用户拒绝授权等）if (isset($_GET['error'])) {
    die('登录失败: ' . htmlspecialchars($_GET['error_description'] ?? $_GET['error']));
}

// 2. 验证state（防止CSRF攻击，非常重要！）if (!isset($_GET['state']) || $_GET['state'] !== ($_SESSION['oauth_state'] ?? '')) {
    die('安全验证失败：state不匹配，请重试');
}

// 3. 获取授权码$code = $_GET['code'] ?? '';
if (empty($code)) {
    die('未收到授权码');
}

// 4. 用授权码换取访问令牌（后端请求，API Secret不会暴露给前端）$ch = curl_init('https://id.jnqj.net/api/oauth.php?action=token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'grant_type'    => 'authorization_code',
    'client_id'     => $API_KEY,
    'client_secret' => $API_SECRET,
    'code'          => $code,
    'redirect_uri'  => $REDIRECT_URI,
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);   // 启用SSL证书验证（必须）curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);       // 验证主机名（必须为2）
$response = curl_exec($ch);
curl_close($ch);

$tokenData = json_decode($response, true);

// 5. 检查是否成功获取令牌if (!isset($tokenData['access_token'])) {
    die('获取令牌失败: ' . ($tokenData['message'] ?? $response));
}

// 6. 保存令牌到Session$_SESSION['access_token']  = $tokenData['access_token'];
$_SESSION['refresh_token'] = $tokenData['refresh_token'] ?? '';

echo '<h1>✅ 登录成功！</h1>';
echo '<p>正在获取用户信息...</p>';
echo '<script>setTimeout(() => location.href = "userinfo.php", 1000);</script>';
?>

<?php
// userinfo.php - 获取金牛ID用户信息
session_start();

$accessToken = $_SESSION['access_token'] ?? '';
if (empty($accessToken)) {
    die('请先登录');
}

// 调用用户信息接口$ch = curl_init('https://id.jnqj.net/api/oauth.php?action=userinfo');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken,  // 注意：令牌放在Header里]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);   // 启用SSL证书验证（必须）curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);       // 验证主机名（必须为2）
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['success'] ?? false) {
    $user = $result['data'];
    
    // 打印用户信息    echo '<h1>欢迎, ' . htmlspecialchars($user['username'] ?? '') . '</h1>';
    echo '<p>邮箱: ' . htmlspecialchars($user['email'] ?? '') . '</p>';
    echo '<p>OpenID: ' . htmlspecialchars($user['openid'] ?? '') . '</p>';
    echo '<p>用户类型: ' . htmlspecialchars($user['user_type'] ?? '') . '</p>';
    echo '<p>实名认证: ' . (($user['real_name_verified'] ?? false) ? '已认证' : '未认证') . '</p>';
    
    if ($user['user_type'] === 'personal') {
        // 个人用户信息        echo '<p>姓名: ' . htmlspecialchars($user['real_name'] ?? '') . '</p>';
        echo '<p>性别: ' . htmlspecialchars($user['gender'] ?? '') . '</p>';
    } elseif ($user['user_type'] === 'enterprise') {
        // 企业用户信息        echo '<p>企业名称: ' . htmlspecialchars($user['enterprise']['enterprise_name'] ?? '') . '</p>';
        echo '<p>统一社会信用代码: ' . htmlspecialchars($user['enterprise']['enterprise_code'] ?? '') . '</p>';
    }
} else {
    echo '获取用户信息失败: ' . ($result['message'] ?? '未知错误');
}
?>

流程图解（看图就懂）

下面用一张图说明整个登录流程，蓝色是用户，金色是金牛ID，绿色是你的应用：

核心概念（大白话版）

如果你是第一次接触OAuth，以下概念可能对你有帮助。如果你已经熟悉OAuth 2.0，可以直接跳到API参考。

接入前检查清单

在开始编码之前，请确认以下事项都已完成：

OAuth 2.0 授权流程

金牛ID采用OAuth 2.0标准的授权码模式（Authorization Code Flow），流程如下：

1. 第三方应用引导用户访问金牛ID授权页面
2. 用户登录并同意授权
3. 金牛ID重定向回第三方应用，携带授权码或错误信息
4. 第三方应用使用授权码换取访问令牌
5. 使用访问令牌获取用户信息

回调错误码说明

当授权过程中出现错误时，金牛ID会将错误信息通过回调地址返回给第三方应用。错误参数如下：

接入指南

用户类型说明

金牛ID支持两种用户类型，请根据您的需求选择合适的认证方式：

1. 注册并完成认证

首先，您需要注册一个金牛ID账号并完成实名认证。企业用户完成企业认证后，需要按照以下流程获取 API 密钥：

企业用户获取 API 密钥流程：

1. 创建应用- 进入应用管理页面，创建新应用（最多300个）
2. 配置白名单- 设置回调域名和IP白名单
3. 创建令牌- 为应用创建 API 令牌（每个应用限1个）
4. 保存密钥- 获取 API Key（Client ID）和 API Secret（Client Secret）

2. 配置回调地址白名单

为了安全起见，金牛ID要求所有回调地址必须在白名单中注册。请在API密钥管理页面配置允许的回调地址。

白名单配置说明

API密钥管理页面提供两个独立的输入框，请分别配置：

配置示例

域名白名单（精确匹配，每行一个域名）：id.jnqj.net
app.yourdomain.com
www.example.com

IP白名单（支持内网IP+端口）：127.0.0.1
127.0.0.1:10008
192.168.1.100:8080
10.0.0.5:3000
[::1]:8080

3. 集成SDK或直接调用API

您可以使用我们提供的代码示例，或者直接调用REST API进行集成。

授权端点

请求参数

请求示例

GET /oauth/authorize?response_type=code&client_id=YOUR_API_KEY&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&state=RANDOM_STATE_STRING&scope=basic%20profile%20idcard&code_challenge=CODE_CHALLENGE_VALUE&code_challenge_method=S256 HTTP/1.1
Host: id.jnqj.net

响应说明

授权成功后，将重定向到回调地址，并携带以下参数：

令牌端点

请求参数

响应示例（RFC 6749 扁平格式）

{
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
    "scope": "basic profile idcard"
}

响应字段说明

用户信息端点

请求头

响应字段说明

企业信息字段（enterprise对象）

响应示例 - 个人用户

{
    "code": 200,
    "message": "获取用户信息成功",
    "data": {
        "user_id": 123,
        "email": "user@example.com",
        "username": "用户名",
        "user_type": "personal",
        "real_name_verified": true,
        "real_name": "张三",
        "idcard_number": "44xxxx********8888",
        "gender": "男",
        "birth_date": "1990-01-01",
        "nation": "汉",
        "city": "广州市",
        "address": "广东省广州市xx区xx路xx号",
        "idcard_issue_authority": "广州市公安局xx分局",
        "idcard_valid_period": "2020-01-01 至 2040-01-01"
    }
}

响应示例 - 企业用户

{
    "code": 200,
    "message": "获取用户信息成功",
    "data": {
        "user_id": 456,
        "email": "enterprise@example.com",
        "username": "企业用户",
        "user_type": "enterprise",
        "real_name_verified": true,
        "real_name": "李四",
        "idcard_number": "440711********8888",
        "gender": "男",
        "birth_date": "1985-05-05",
        "nation": "汉",
        "city": "深圳市",
        "address": "广东省深圳市xx区xx路xx号",
        "idcard_issue_authority": "深圳市公安局xx分局",
        "idcard_valid_period": "2019-01-01 至 2039-01-01",
        "enterprise": {
            "enterprise_name": "金牛奇迹科技有限公司",
            "enterprise_code": "91440300XXXXXXXXXX",
            "enterprise_type": "有限责任公司",
            "registered_capital": "1000万元",
            "established_date": "2020-01-01",
            "business_scope": "软件开发、技术服务、技术咨询等",
            "verified_at": "2024-01-15 10:30:00",
            "legal_person_name": "李四"
        }
    }
}

错误状态码说明

资质信息端点

请求方式

仅支持通过 Authorization Header 传递访问令牌：

Authorization: Bearer {access_token}

响应数据结构

接口会根据用户类型（user_type字段）自动返回相应的信息。

个人用户响应字段

企业用户响应字段

企业信息对象（enterprise）

法人信息对象（legal_person）

响应示例 - 个人用户

{
    "code": 200,
    "message": "获取个人资质信息成功",
    "data": {
        "openid": "jn_openid_abc123def456",
        "user_id": 32,
        "email": "user@example.com",
        "username": "金牛用户",
        "user_type": "personal",
        "real_name": "黎汉杰",
        "gender": "男",
        "nation": "汉",
        "birth_date": "1983-11-29",
        "address": "广东省江门市蓬江区建设路15号606",
        "city": "江门市",
        "idcard_number": "**************5113",
        "idcard_valid_from": "2017-10-26",
        "idcard_valid_to": "2037-10-26",
        "idcard_front_image": "https://id.jnqj.net/uploads/idcard/jn_openid_abc123def456/20260508_lYUGcaGwq4Q2zy09.jpg",
        "idcard_back_image": "https://id.jnqj.net/uploads/idcard/jn_openid_abc123def456/20260508_2wyutHT78C6cfCmn.jpg"
    }
}

响应示例 - 企业用户

{
    "code": 200,
    "message": "获取企业资质信息成功",
    "data": {
        "openid": "jn_openid_xyz7890123",
        "user_id": 6,
        "email": "enterprise@example.com",
        "username": "金牛企业",
        "user_type": "enterprise",
        "enterprise": {
            "enterprise_name": "金牛奇迹科技有限公司",
            "enterprise_code": "91440300XXXXXXXXXX",
            "enterprise_type": "有限责任公司",
            "registered_capital": "1000万元",
            "establishment_date": "2020-01-01",
            "registered_address": "广东省深圳市南山区科技园",
            "business_scope": "软件开发、技术服务、技术咨询等",
            "verified_at": "2024-01-15 10:30:00",
            "business_license_image": "https://id.jnqj.net/uploads/enterprise/jn_openid_xyz7890123/license.jpg"
        },
        "legal_person": {
            "legal_person_name": "张三",
            "legal_person_idcard": "**************8888",
            "legal_person_idcard_front": "https://id.jnqj.net/uploads/enterprise/jn_openid_xyz7890123/legal_front.jpg",
            "legal_person_idcard_back": "https://id.jnqj.net/uploads/enterprise/jn_openid_xyz7890123/legal_back.jpg"
        }
    }
}

错误状态码说明

刷新令牌

访问令牌有效期为2小时，过期后可以使用刷新令牌获取新的访问令牌。

请求参数

响应示例（RFC 6749 扁平格式）

{
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "NEW_REFRESH_TOKEN_VALUE...",
    "scope": "basic profile idcard"
}

扫码登录

扫码登录是一种便捷的第三方登录方式，用户只需使用金牛ID App 扫描二维码即可完成授权登录，无需输入账号密码。

扫码登录流程

1. 第三方应用调用create接口创建二维码
2. 第三方应用展示二维码给用户
3. 用户使用金牛ID App 扫描二维码
4. 用户在手机上确认授权
5. 第三方应用轮询status接口获取登录状态
6. 用户确认后，第三方应用获取 access_token
7. 使用 access_token 获取用户信息

扫码登录API接口

1. 创建二维码

请求参数

响应示例

{
    "success": true,
    "message": "二维码创建成功",
    "data": {
        "qr_code": "qr_a1b2c3d4e5f6...",
        "qr_url": "https://id.jnqj.net/qrlogin/scan?code=qr_a1b2c3d4e5f6...",
        "expires_in": 300,
        "expires_at": "2026-02-04 12:05:00"
    }
}

2. 查询二维码状态

请求参数

状态说明

响应示例（已确认）

{
    "success": true,
    "data": {
        "status": 2,
        "status_text": "已确认",
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "token_type": "Bearer",
        "expires_in": 7200
    }
}

3. 获取用户信息

请求头

响应字段说明

扫码登录获取的用户信息字段与OAuth用户信息接口完全一致：

响应示例

{
    "success": true,
    "message": "获取成功",
    "data": {
        "openid": "123456789012345678901234567890XX",
        "real_name_verified": true,
        "real_name": "真实姓名",
        "idcard_number": "440711********8888",
        "gender": "男",
        "birth_date": "xxxx-xx-xx",
        "city": "城市名称",
        "idcard_issue_authority": "xx市公安局xx分局",
        "idcard_valid_period": "xxxx-xx-xx 至 xxxx-xx-xx"
    }
}

扫码登录SDK

我们提供了多语言的扫码登录SDK，包含完整的二维码生成、状态轮询、用户信息获取等功能。

SDK包含以下核心功能：

• createQrCode()- 创建二维码
• queryStatus(qrCode)- 查询二维码状态
• pollStatus(qrCode, timeout, callback)- 轮询等待用户确认
• getUserInfo(accessToken)- 获取用户信息
• refreshToken(refreshToken)- 刷新访问令牌

下载扫码登录SDK

安全防护总览

金牛ID平台实施了多层安全防护机制，覆盖从请求接入到令牌管理的完整生命周期。以下章节逐一说明各项安全措施，帮助开发者快速理解并正确配置。

CSRF防护（跨站请求伪造防护）

金牛ID对所有POST请求实施CSRF令牌验证机制，防止恶意网站伪造用户请求。

CSRF令牌使用方式

所有POST请求必须携带CSRF令牌，支持以下两种方式传递：

代码示例：在表单中添加CSRF令牌

<?php
// PHP：在表单中嵌入CSRF令牌session_start();
$csrfToken = $_SESSION['csrf_token'] ?? bin2hex(random_bytes(32));
$_SESSION['csrf_token'] = $csrfToken;
?>

<!-- HTML表单中添加隐藏字段 -->
<form method="POST" action="/api/login.php">
    <input type="hidden" name="csrf_token" value="<?php echo $csrfToken; ?>">
    <input type="text" name="username" placeholder="用户名">
    <input type="password" name="password" placeholder="密码">
    <button type="submit">登录</button>
</form>

<!-- AJAX请求中通过Header传递 -->
<script>
fetch('/api/login.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'X-CSRF-Token': '<?php echo $csrfToken; ?>'
    },
    body: 'username=user&password=pass'
});
</script>

密码安全策略

金牛ID对用户密码实施强制安全策略，确保密码强度满足安全要求。

密码强度要求

回调地址白名单与HTTPS强制

金牛ID对回调地址实施严格的安全管控，确保授权回调不会被劫持到恶意网站。

白名单强制要求

令牌安全机制

金牛ID对Access Token和Refresh Token实施多重安全保护，符合OAuth 2.0安全最佳实践（RFC 9700）。

Access Token安全

Refresh Token安全

安全图片访问

身份证、营业执照等敏感图片采用多层安全保护，确保用户隐私数据不被未授权访问。

安全图片访问机制

SSL证书验证与安全响应头

金牛ID对所有出站请求启用SSL证书验证，并设置了完整的安全响应头，防范中间人攻击和各类Web安全威胁。

SSL证书验证

// PHP cURL - 必须启用SSL验证$ch = curl_init('https://id.jnqj.net/api/oauth.php?action=token');
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);   // 验证对端证书（必须为true）curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);       // 验证主机名（必须为2）// 不要设置为 false 或 0，否则存在中间人攻击风险！
// Python requests - 默认已启用SSL验证，不要关闭response = requests.post(url, data=data)  # 正确：默认verify=True# 不要使用 verify=False，否则存在安全风险！
// Node.js axios - 默认已启用SSL验证const response = await axios.post(url, data);  // 正确：默认验证SSL// 不要设置 rejectUnauthorized: false！
// Java HttpURLConnection - 默认已启用SSL验证// 使用默认的HttpsURLConnection即可，无需额外配置

安全响应头

金牛ID服务器返回以下安全响应头，保护用户浏览器免受常见Web攻击：

Scope 授权范围机制

金牛ID实现了基于OAuth 2.0的scope授权范围机制，遵循 PIPL（个人信息保护法）最小必要原则和单独同意原则。第三方应用通过scope参数申请所需的权限范围，系统据此限制令牌可访问的字段，确保应用只能获取其业务所需的信息。

可用Scope列表

请求示例

GET /oauth/authorize?response_type=code
    &client_id=YOUR_API_KEY
    &redirect_uri=https://app.example.com/callback
    &state=RANDOM_STATE
    &scope=basic%20profile%20idcard%20qualification

PKCE 安全指南（RFC 7636）

PKCE（Proof Key for Code Exchange）是OAuth 2.0的安全扩展，用于防止授权码注入攻击。RFC 9700（OAuth 2.0 Security BCP）要求所有授权服务器必须支持PKCE。金牛ID已全面支持PKCE，强烈建议所有第三方应用启用。

PKCE工作流程

1. 客户端生成一个高熵随机字符串code_verifier（43-128字符）
2. 客户端计算code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
3. 客户端在授权请求中发送code_challenge和code_challenge_method=S256
4. 授权服务器存储code_challenge并返回授权码
5. 客户端在令牌交换请求中发送code_verifier
6. 授权服务器验证 SHA256(code_verifier) 是否匹配存储的 code_challenge

各语言PKCE实现示例

PHP

// 1. 生成 code_verifier$codeVerifier = rtrim(strtr(base64_encode(random_bytes(32)), '+/', '-_'), '=');

// 2. 生成 code_challenge (S256)$codeChallenge = rtrim(strtr(base64_encode(hash('sha256', $codeVerifier, true)), '+/', '-_'), '=');

// 3. 构建授权URL$authUrl = 'https://id.jnqj.net/oauth/authorize?response_type=code'
    . '&client_id=' . urlencode($apiKey)
    . '&redirect_uri=' . urlencode($callbackUrl)
    . '&state=' . urlencode($state)
    . '&code_challenge=' . $codeChallenge
    . '&code_challenge_method=S256';

// 4. 令牌交换时传入 code_verifier$tokenParams = [
    'grant_type' => 'authorization_code',
    'client_id' => $apiKey,
    'client_secret' => $apiSecret,
    'code' => $authCode,
    'redirect_uri' => $callbackUrl,
    'code_verifier' => $codeVerifier, // PKCE验证器];

JavaScript / Node.js

const crypto = require('crypto');

// 1. 生成 code_verifierconst codeVerifier = crypto.randomBytes(32).toString('base64url');

// 2. 生成 code_challenge (S256)const codeChallenge = crypto.createHash('sha256')
    .update(codeVerifier).digest('base64url');

// 3. 构建授权URLconst authUrl = `https://id.jnqj.net/oauth/authorize?response_type=code`
    + `&client_id=${encodeURIComponent(apiKey)}`
    + `&redirect_uri=${encodeURIComponent(callbackUrl)}`
    + `&state=${encodeURIComponent(state)}`
    + `&code_challenge=${codeChallenge}`
    + `&code_challenge_method=S256`;

// 4. 令牌交换时传入 code_verifierconst tokenParams = new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: apiKey,
    client_secret: apiSecret,
    code: authCode,
    redirect_uri: callbackUrl,
    code_verifier: codeVerifier, // PKCE验证器});

签名URL机制

资质信息端点返回的身份证照片、营业执照等敏感图片URL采用HMAC-SHA256签名机制，替代了此前"可直接访问"的方式。此机制遵循 PIPL 第51条数据安全保护义务。

签名URL特性

签名URL格式

https://id.jnqj.net/api/secure_image.php?path=BASE64_ENCODED_PATH&expires=TIMESTAMP&nonce=RANDOM_HEX&uid=USER_ID&sig=HMAC_SIGNATURE

速率限制

为防止暴力枚举和滥用，金牛ID对所有API端点实施了IP级速率限制。超过限制时返回 HTTP 429 状态码和slow_down错误。

限流响应

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
    "success": false,
    "error": "slow_down",
    "error_description": "请求过于频繁，请稍后再试"
}

令牌撤销端点（RFC 7009）

令牌撤销端点允许客户端主动通知授权服务器撤销先前获取的令牌，用于处理用户登出、令牌泄露等场景。

请求参数

响应说明

无论令牌是否存在，服务端都返回 HTTP 200 和空JSON体{}（RFC 7009 §2.2，不通过错误码泄露令牌是否存在）。

令牌内省端点（RFC 7662）

令牌内省端点允许资源服务器查询令牌的有效性、关联的用户和权限范围。由于金牛ID的 access_token 为不透明令牌（非JWT），第三方应用需通过内省端点验证令牌。

请求参数

响应示例（有效令牌）

{
    "active": true,
    "scope": "basic profile idcard",
    "client_id": "jn_xxxxxxxxxxxx",
    "username": "jenico",
    "token_type": "Bearer",
    "exp": 1782698000,
    "iat": 1782690800,
    "sub": "12345"
}

响应示例（无效/过期/已撤销令牌）

{
    "active": false
}

发现端点（RFC 8414）

金牛ID提供OAuth 2.0授权服务器元数据发现端点，允许客户端自动获取端点地址、支持的授权类型、签名密钥等配置信息。

授权服务器元数据

{
    "issuer": "https://id.jnqj.net",
    "authorization_endpoint": "https://id.jnqj.net/oauth/authorize",
    "token_endpoint": "https://id.jnqj.net/api/oauth.php?action=token",
    "revocation_endpoint": "https://id.jnqj.net/api/oauth.php?action=revocation",
    "introspection_endpoint": "https://id.jnqj.net/api/oauth.php?action=introspect",
    "jwks_uri": "https://id.jnqj.net/.well-known/jwks.json",
    "response_types_supported": ["code"],
    "grant_types_supported": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic"],
    "scopes_supported": ["basic", "profile", "idcard", "enterprise", "qualification"],
    "code_challenge_methods_supported": ["S256", "plain"],
    "token_types_supported": ["Bearer"]
}

JWKS端点

错误码参考

金牛ID API采用RFC 6749 §5.2标准错误响应格式。

标准错误响应格式

{
    "success": false,
    "error": "invalid_request",
    "error_description": "缺少必要的参数"
}

错误码列表

授权端点错误回调

安全最佳实践

以下是金牛ID为第三方应用开发者提供的安全最佳实践建议，帮助您在接入过程中最大程度地保护用户数据和系统安全。

1. 密钥存储建议

// PHP 正确的密钥存储方式// .env 文件内容：// JNQJ_API_KEY=jn_your_api_key_here
// JNQJ_API_SECRET=sk_your_api_secret_here

// PHP 代码中读取：$apiKey = getenv('JNQJ_API_KEY');
$apiSecret = getenv('JNQJ_API_SECRET');

// .gitignore 文件中加入：// .env

2. Token 存储建议

// PHP 正确的Token存储方式（HttpOnly Cookie）session_start();

// 获取令牌后，存储到Session中$_SESSION['access_token'] = $tokenData['access_token'];
$_SESSION['refresh_token'] = $tokenData['refresh_token'];

// 或者使用HttpOnly Cookie（注意需要HTTPS）setcookie('access_token', $tokenData['access_token'], [
    'expires'  => time() + 7200,     // 2小时有效期    'path'     => '/',
    'secure'   => true,               // 仅HTTPS传输    'httponly' => true,                // JavaScript不可读    'samesite' => 'Strict',           // 防止CSRF]);

3. 错误处理建议

// PHP 正确的错误处理方式try {
    $tokenInfo = $oauth->getAccessToken($code, $redirectUri);
    if (!isset($tokenInfo['access_token'])) {
        // 记录详细错误到服务器日志（不暴露给用户）        error_log('OAuth token exchange failed: ' . json_encode($tokenInfo));
        // 返回友好的错误提示        throw new Exception('登录服务暂时不可用，请稍后重试');
    }
} catch (Exception $e) {
    // 记录详细错误到日志    error_log('OAuth error: ' . $e->getMessage());
    // 向用户显示友好错误    $_SESSION['error_message'] = '登录过程中出现问题，请重试';
    header('Location: /login');
    exit;
}

4. 日志记录建议

// PHP 正确的日志记录方式// 定义需要脱敏的字段$sensitiveFields = ['password', 'client_secret', 'access_token', 
                    'refresh_token', 'idcard_number', 'real_name'];

function safeLog($message, $context = []) {
    $sensitiveFields = ['password', 'client_secret', 'access_token', 
                        'refresh_token', 'idcard_number', 'real_name'];
    
    // 脱敏处理    foreach ($sensitiveFields as $field) {
        if (isset($context[$field])) {
            $context[$field] = '***REDACTED***';
        }
    }
    
    // 记录日志（不含敏感信息）    error_log($message . ': ' . json_encode($context));
}

// 使用示例safeLog('OAuth login attempt', [
    'client_id' => $apiKey,
    'user_ip'   => $_SERVER['REMOTE_ADDR'],
    'result'    => 'success',
    // 以下字段会被自动脱敏    'password'  => $userPassword,  // 记录为 ***REDACTED***
]);

技术架构概览

金牛 ID 平台采用业界领先的技术架构，以OAuth 2.0 + OpenID Connect作为身份认证协议，通过RESTful API提供标准化接口服务，依托ELK 日志系统实现全流程审计监控，三位一体构建安全、可靠、高效的统一身份认证体系。

一、身份协议：OAuth 2.0 + OpenID Connect（OIDC）

一句话定位：金牛 ID 对外 "开放登录" 的标准安全规则，让别的网站 / 应用能安全用金牛账号登录，不泄露密码。

1）OAuth 2.0（授权协议）

核心作用：安全授权，不暴露用户密码，权限可控

金牛场景流程：

1. 合作网站 / 游戏想接入金牛登录
2. 用户点击 "金牛 ID 登录" → 跳转到 id.jnqj.net
3. 用户同意授权（比如 "允许获取昵称 / 头像"）
4. 金牛给第三方发临时令牌（Access Token）
5. 第三方用令牌访问用户资源，全程看不到密码

2）OpenID Connect（OIDC，身份认证层）

关键升级：多了ID Token（加密 JWT），包含：

• 用户唯一 ID（sub）
• 昵称、邮箱、头像等基础信息
• 加密签名，防篡改、可验证

金牛场景：

• 第三方不仅要 "授权"，还要 "知道用户身份"
• 登录成功后，金牛返回Access Token + ID Token
• 第三方解析 ID Token，直接拿到用户身份，不用再查库

3）对金牛 ID 的业务价值

二、接口：RESTful API（登录 / 授权 / 用户信息）

一句话定位：金牛 ID 对外提供的标准化 "功能调用入口"，让第三方 / 内部系统能程序化调用登录、授权、获取用户信息。

1）什么是 RESTful API（大白话）

• 把所有功能看成"资源"（用户、登录、授权）
• 用URL 定位资源，用HTTP 方法（GET/POST/PUT/DELETE）表示操作

接口示例：

特点：无状态、标准化、易扩展、前后端 / 跨系统通用

2）金牛 ID 核心接口（业务视角）

🔑 登录接口：POST /api/auth/login

🔓 授权接口：POST /api/oauth/authorize

用户信息接口：GET /api/user/info

🔄 令牌校验 / 刷新：POST /api/oauth/token

3）对金牛 ID 的业务价值

三、日志：ELK / 自研日志系统（登录审计、异常监控）

一句话定位：金牛 ID 的"黑匣子 + 监控大屏"，记录所有登录 / 授权行为，可追溯、可告警、可排查问题。

1）ELK 是什么（大白话）

2）金牛 ID 日志记录什么（核心审计字段）

每条日志必含：

3）两大核心业务作用

登录审计（可追溯）

• 谁、何时、何地、用什么设备登录
• 授权给谁、授权了什么权限
• 出问题可回溯每一步操作，定位责任

异常监控（安全告警）

规则示例：

作用：防暴力破解、防盗号、防恶意授权

4）对金牛 ID 的业务价值

四、三者在金牛 ID 中的关系（业务闭环）

企业用户应用管理

一句话定位：企业用户通过应用管理系统，可以创建和管理多个应用，每个应用对应独立的 API 令牌，实现精细化的权限控制和业务隔离。

应用管理架构

应用场景示例

• 多业务线管理：企业有多个业务系统（官网、APP、小程序），每个系统创建一个独立应用
• 多环境隔离：开发环境、测试环境、生产环境分别创建不同应用，避免令牌混用
• 第三方接入：为不同的合作伙伴创建独立应用，便于权限管理和审计追踪
• 项目制管理：按项目维度创建应用，项目结束后可单独禁用或删除

创建应用

企业用户登录后，进入应用管理页面，按照以下步骤创建新应用：

创建流程

应用信息字段说明

应用列表管理

企业用户可以在应用列表页面查看和管理所有已创建的应用：

应用列表功能

应用状态说明

创建令牌

应用创建成功后，需要为应用创建 API 令牌才能进行接口调用。每个应用只能创建一个令牌。

令牌创建流程

令牌信息说明

令牌管理

令牌创建后，企业用户可以在应用详情页查看和管理令牌状态：

令牌管理操作

最佳实践

1. 定期轮换：建议每 90 天重置一次令牌，降低密钥泄露风险
2. 环境隔离：不同环境（开发/测试/生产）使用不同应用和令牌
3. 权限最小化：按业务需求配置回调白名单，避免使用通配符
4. 安全存储：API Secret 存储在服务器环境变量或密钥管理系统中
5. 监控告警：关注令牌的使用情况和异常调用日志

限制说明

PHP 示例

<?php
// 金牛ID OAuth 登录集成示例// 请替换为您的API密钥$apiKey = 'your_api_key_here';
$apiSecret = 'your_api_secret_here';

// 请替换为您的回调地址$redirectUri = 'https://your-domain.com/callback.php';

class JnqjOAuth {
    private $apiKey;
    private $apiSecret;
    private $baseUrl = 'https://id.jnqj.net';

    public function __construct($apiKey, $apiSecret) {
        $this->apiKey = $apiKey;
        $this->apiSecret = $apiSecret;
    }

    // 生成PKCE code_verifier    public function generateCodeVerifier() {
        return rtrim(strtr(base64_encode(random_bytes(32)), '+/', '-_'), '=');
    }

    // 生成PKCE code_challenge (S256)    public function generateCodeChallenge($codeVerifier) {
        return rtrim(strtr(base64_encode(hash('sha256', $codeVerifier, true)), '+/', '-_'), '=');
    }

    // 获取授权URL（state必填，支持PKCE和scope）    public function getAuthUrl($redirectUri, $state, $scope = 'basic', $codeChallenge = null) {
        $params = [
            'client_id' => $this->apiKey,
            'redirect_uri' => $redirectUri,
            'response_type' => 'code',
            'state' => $state,
            'scope' => $scope,
        ];
        if ($codeChallenge) {
            $params['code_challenge'] = $codeChallenge;
            $params['code_challenge_method'] = 'S256';
        }
        return $this->baseUrl . '/oauth/authorize?' . http_build_query($params);
    }
    
    // 获取访问令牌（支持PKCE）    public function getAccessToken($code, $redirectUri, $codeVerifier = null) {
        $data = [
            'grant_type' => 'authorization_code',
            'client_id' => $this->apiKey,
            'client_secret' => $this->apiSecret,
            'code' => $code,
            'redirect_uri' => $redirectUri,
        ];
        if ($codeVerifier) {
            $data['code_verifier'] = $codeVerifier;
        }
        
        $ch = curl_init($this->baseUrl . '/api/oauth.php?action=token');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    // 获取用户信息    public function getUserInfo($accessToken) {
        $ch = curl_init($this->baseUrl . '/api/oauth.php?action=userinfo');
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $accessToken]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);   // 启用SSL证书验证        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    // 撤销令牌 (RFC 7009)    public function revokeToken($token, $tokenTypeHint = 'access_token') {
        $data = [
            'token' => $token,
            'token_type_hint' => $tokenTypeHint,
            'client_id' => $this->apiKey,
            'client_secret' => $this->apiSecret,
        ];
        $ch = curl_init($this->baseUrl . '/api/oauth.php?action=revocation');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);   // 启用SSL证书验证        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
        curl_exec($ch);
        curl_close($ch);
    }
}

// 使用示例$oauth = new JnqjOAuth('YOUR_API_KEY', 'YOUR_API_SECRET');

// 1. 生成PKCE参数$codeVerifier = $oauth->generateCodeVerifier();
$codeChallenge = $oauth->generateCodeChallenge($codeVerifier);

// 2. 生成授权URL（state必填）$state = bin2hex(random_bytes(16)); // 生成随机state$authUrl = $oauth->getAuthUrl(
    'https://app.example.com/callback',
    $state,
    'basic profile idcard',
    $codeChallenge
);

// 3. 用户授权后，用授权码交换令牌$tokenInfo = $oauth->getAccessToken($authCode, 'https://app.example.com/callback', $codeVerifier);
// $tokenInfo['access_token'] - 访问令牌// $tokenInfo['refresh_token'] - 刷新令牌（每次刷新轮换）// $tokenInfo['scope'] - 授予的权限范围

Python 示例

import requests
import urllib.parse

class JnqjOAuth:
    def __init__(self, api_key, api_secret):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = 'https://id.jnqj.net'
    
    # 获取授权URL    def get_auth_url(self, redirect_uri, state=''):
        params = {
            'client_id': self.api_key,
            'redirect_uri': redirect_uri,
            'response_type': 'code',
            'state': state,
        }
        return f"{self.base_url}/oauth/authorize?{urllib.parse.urlencode(params)}"
    
    # 获取访问令牌    def get_access_token(self, code, redirect_uri):
        data = {
            'grant_type': 'authorization_code',
            'client_id': self.api_key,
            'client_secret': self.api_secret,
            'code': code,
            'redirect_uri': redirect_uri,
        }
        
        # action=token 必须通过 URL 参数传递        response = requests.post(
            f"{self.base_url}/api/oauth.php?action=token",
            data=data,
            headers={'Content-Type': 'application/x-www-form-urlencoded'}
        )
        return response.json()
    
    # 获取用户信息    def get_user_info(self, access_token):
        headers = {'Authorization': f'Bearer {access_token}'}
        response = requests.get(
            f"{self.base_url}/api/oauth.php?action=userinfo",
            headers=headers
        )
        return response.json()
    
    # 刷新令牌    def refresh_token(self, refresh_token):
        data = {
            'grant_type': 'refresh_token',
            'client_id': self.api_key,
            'client_secret': self.api_secret,
            'refresh_token': refresh_token,
        }
        
        # action=token 必须通过 URL 参数传递        response = requests.post(
            f"{self.base_url}/api/oauth.php?action=token",
            data=data,
            headers={'Content-Type': 'application/x-www-form-urlencoded'}
        )
        return response.json()


# Flask 完整示例from flask import Flask, request, redirect, session

app = Flask(__name__)
app.secret_key = 'your-secret-key'

oauth = JnqjOAuth('your-api-key', 'your-api-secret')
REDIRECT_URI = 'http://localhost:5000/callback'

@app.route('/login')
def login():
    import secrets
    state = secrets.token_urlsafe(16)
    session['oauth_state'] = state
    auth_url = oauth.get_auth_url(REDIRECT_URI, state)
    return redirect(auth_url)

@app.route('/callback')
def callback():
    code = request.args.get('code')
    state = request.args.get('state')
    
    # 验证 state 防止 CSRF 攻击    if state != session.get('oauth_state'):
        return 'Invalid state', 400
    
    # 获取访问令牌    token_data = oauth.get_access_token(code, REDIRECT_URI)
    if token_data.get('success'):
        session['access_token'] = token_data['data']['access_token']
        return redirect('/profile')
    return 'Authentication failed', 400

@app.route('/profile')
def profile():
    access_token = session.get('access_token')
    if not access_token:
        return redirect('/login')
    
    user_info = oauth.get_user_info(access_token)
    return user_info

Java 示例

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import java.util.stream.Collectors;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class JnqjOAuth {
    private String apiKey;
    private String apiSecret;
    private String baseUrl = "https://id.jnqj.net";
    private Gson gson = new Gson();
    
    public JnqjOAuth(String apiKey, String apiSecret) {
        this.apiKey = apiKey;
        this.apiSecret = apiSecret;
    }
    
    // 获取授权URL    public String getAuthUrl(String redirectUri, String state) throws Exception {
        Map<String, String> params = new HashMap<>();
        params.put("client_id", apiKey);
        params.put("redirect_uri", redirectUri);
        params.put("response_type", "code");
        params.put("state", state);
        
        String queryString = params.entrySet().stream()
            .map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));
        
        return baseUrl + "/oauth/authorize?" + queryString;
    }
    
    // 获取访问令牌    public JsonObject getAccessToken(String code, String redirectUri) throws Exception {
        String url = baseUrl + "/api/oauth.php";
        Map<String, String> params = new HashMap<>();
        params.put("grant_type", "authorization_code");
        params.put("client_id", apiKey);
        params.put("client_secret", apiSecret);
        params.put("code", code);
        params.put("redirect_uri", redirectUri);
        
        String postData = params.entrySet().stream()
            .map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));
        
        return sendPostRequest(url, postData);
    }
    
    // 获取用户信息    public JsonObject getUserInfo(String accessToken) throws Exception {
        String url = baseUrl + "/api/oauth.php?action=userinfo";
        return sendGetRequest(url, accessToken);
    }
    
    // 刷新令牌    public JsonObject refreshToken(String refreshToken) throws Exception {
        String url = baseUrl + "/api/oauth.php";
        Map<String, String> params = new HashMap<>();
        params.put("grant_type", "refresh_token");
        params.put("client_id", apiKey);
        params.put("client_secret", apiSecret);
        params.put("refresh_token", refreshToken);
        
        String postData = params.entrySet().stream()
            .map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));
        
        return sendPostRequest(url, postData);
    }
    
    private JsonObject sendPostRequest(String urlString, String postData) throws Exception {
        URL url = new URL(urlString);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
        conn.setDoOutput(true);
        
        try (DataOutputStream wr = new DataOutputStream(conn.getOutputStream())) {
            wr.writeBytes(postData);
            wr.flush();
        }
        
        return parseResponse(conn);
    }
    
    private JsonObject sendGetRequest(String urlString, String accessToken) throws Exception {
        URL url = new URL(urlString);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        conn.setRequestProperty("Authorization", "Bearer " + accessToken);
        
        return parseResponse(conn);
    }
    
    private JsonObject parseResponse(HttpURLConnection conn) throws Exception {
        BufferedReader in = new BufferedReader(
            new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8));
        StringBuilder response = new StringBuilder();
        String line;
        while ((line = in.readLine()) != null) {
            response.append(line);
        }
        in.close();
        return gson.fromJson(response.toString(), JsonObject.class);
    }
}


// Spring Boot 完整示例import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.view.RedirectView;
import javax.servlet.http.HttpSession;

@RestController
public class OAuthController {
    
    private final JnqjOAuth oauth = new JnqjOAuth("your-api-key", "your-api-secret");
    private final String REDIRECT_URI = "http://localhost:8080/callback";
    
    @GetMapping("/login")
    public RedirectView login(HttpSession session) throws Exception {
        String state = java.util.UUID.randomUUID().toString();
        session.setAttribute("oauth_state", state);
        String authUrl = oauth.getAuthUrl(REDIRECT_URI, state);
        return new RedirectView(authUrl);
    }
    
    @GetMapping("/callback")
    public String callback(@RequestParam String code, 
                          @RequestParam String state,
                          HttpSession session) throws Exception {
        // 验证 state        if (!state.equals(session.getAttribute("oauth_state"))) {
            return "Invalid state";
        }
        
        // 获取访问令牌        JsonObject tokenData = oauth.getAccessToken(code, REDIRECT_URI);
        if (tokenData.get("success").getAsBoolean()) {
            String accessToken = tokenData.getAsJsonObject("data")
                .get("access_token").getAsString();
            session.setAttribute("access_token", accessToken);
            return "redirect:/profile";
        }
        return "Authentication failed";
    }
    
    @GetMapping("/profile")
    public JsonObject profile(HttpSession session) throws Exception {
        String accessToken = (String) session.getAttribute("access_token");
        if (accessToken == null) {
            throw new RuntimeException("Not authenticated");
        }
        return oauth.getUserInfo(accessToken);
    }
}

Node.js 示例

const axios = require('axios');
const querystring = require('querystring');

class JnqjOAuth {
    constructor(apiKey, apiSecret) {
        this.apiKey = apiKey;
        this.apiSecret = apiSecret;
        this.baseUrl = 'https://id.jnqj.net';
    }
    
    // 获取授权URL    getAuthUrl(redirectUri, state = '') {
        const params = new URLSearchParams({
            client_id: this.apiKey,
            redirect_uri: redirectUri,
            response_type: 'code',
            state: state,
        });
        return `${this.baseUrl}/oauth/authorize?${params.toString()}`;
    }
    
    // 获取访问令牌    async getAccessToken(code, redirectUri) {
        const data = {
            grant_type: 'authorization_code',
            client_id: this.apiKey,
            client_secret: this.apiSecret,
            code: code,
            redirect_uri: redirectUri,
        };
        
        const response = await axios.post(
            `${this.baseUrl}/api/oauth.php`,
            querystring.stringify(data),
            {
                headers: {
                    'Content-Type': 'application/x-www-form-urlencoded'
                }
            }
        );
        return response.data;
    }
    
    // 获取用户信息    async getUserInfo(accessToken) {
        const response = await axios.get(
            `${this.baseUrl}/api/oauth.php?action=userinfo`,
            {
                headers: {
                    'Authorization': `Bearer ${accessToken}`
                }
            }
        );
        return response.data;
    }
    
    // 刷新令牌    async refreshToken(refreshToken) {
        const data = {
            grant_type: 'refresh_token',
            client_id: this.apiKey,
            client_secret: this.apiSecret,
            refresh_token: refreshToken,
        };
        
        const response = await axios.post(
            `${this.baseUrl}/api/oauth.php`,
            querystring.stringify(data),
            {
                headers: {
                    'Content-Type': 'application/x-www-form-urlencoded'
                }
            }
        );
        return response.data;
    }
}


// Express 完整示例const express = require('express');
const session = require('express-session');
const crypto = require('crypto');

const app = express();
app.use(session({
    secret: 'your-secret-key',
    resave: false,
    saveUninitialized: true
}));

const oauth = new JnqjOAuth('your-api-key', 'your-api-secret');
const REDIRECT_URI = 'http://localhost:3000/callback';

// 登录路由app.get('/login', (req, res) => {
    const state = crypto.randomBytes(16).toString('hex');
    req.session.oauthState = state;
    const authUrl = oauth.getAuthUrl(REDIRECT_URI, state);
    res.redirect(authUrl);
});

// 回调路由app.get('/callback', async (req, res) => {
    const { code, state } = req.query;
    
    // 验证 state    if (state !== req.session.oauthState) {
        return res.status(400).send('Invalid state');
    }
    
    try {
        // 获取访问令牌        const tokenData = await oauth.getAccessToken(code, REDIRECT_URI);
        if (tokenData.success) {
            req.session.accessToken = tokenData.data.access_token;
            res.redirect('/profile');
        } else {
            res.status(400).send('Authentication failed');
        }
    } catch (error) {
        res.status(500).send(error.message);
    }
});

// 用户信息路由app.get('/profile', async (req, res) => {
    const accessToken = req.session.accessToken;
    if (!accessToken) {
        return res.redirect('/login');
    }
    
    try {
        const userInfo = await oauth.getUserInfo(accessToken);
        res.json(userInfo);
    } catch (error) {
        res.status(500).send(error.message);
    }
});

app.listen(3000, () => {
    console.log('Server running on http://localhost:3000');
});

其他语言示例

Go 示例

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "strings"
)

type JnqjOAuth struct {
    APIKey    string
    APISecret string
    BaseURL   string
}

func NewJnqjOAuth(apiKey, apiSecret string) *JnqjOAuth {
    return &JnqjOAuth{
        APIKey:    apiKey,
        APISecret: apiSecret,
        BaseURL:   "https://id.jnqj.net",
    }
}

// 获取授权URLfunc (o *JnqjOAuth) GetAuthUrl(redirectUri, state string) string {
    params := url.Values{}
    params.Set("client_id", o.APIKey)
    params.Set("redirect_uri", redirectUri)
    params.Set("response_type", "code")
    params.Set("state", state)
    return fmt.Sprintf("%s/oauth/authorize?%s", o.BaseURL, params.Encode())
}

// 获取访问令牌func (o *JnqjOAuth) GetAccessToken(code, redirectUri string) (map[string]interface{}, error) {
    data := url.Values{}
    data.Set("grant_type", "authorization_code")
    data.Set("client_id", o.APIKey)
    data.Set("client_secret", o.APISecret)
    data.Set("code", code)
    data.Set("redirect_uri", redirectUri)
    
    resp, err := http.Post(
        o.BaseURL+"/api/oauth.php",
        "application/x-www-form-urlencoded",
        strings.NewReader(data.Encode()),
    )
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    var result map[string]interface{}
    json.Unmarshal(body, &result)
    return result, nil
}

// 获取用户信息func (o *JnqjOAuth) GetUserInfo(accessToken string) (map[string]interface{}, error) {
    req, _ := http.NewRequest("GET", o.BaseURL+"/api/oauth.php?action=userinfo", nil)
    req.Header.Set("Authorization", "Bearer "+accessToken)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    var result map[string]interface{}
    json.Unmarshal(body, &result)
    return result, nil
}

C# / .NET 示例

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
using System.Web;

public class JnqjOAuth
{
    private string _apiKey;
    private string _apiSecret;
    private string _baseUrl = "https://id.jnqj.net";
    private HttpClient _httpClient;
    
    public JnqjOAuth(string apiKey, string apiSecret)
    {
        _apiKey = apiKey;
        _apiSecret = apiSecret;
        _httpClient = new HttpClient();
    }
    
    // 获取授权URL    public string GetAuthUrl(string redirectUri, string state)
    {
        var queryParams = new Dictionary<string, string>
        {
            ["client_id"] = _apiKey,
            ["redirect_uri"] = redirectUri,
            ["response_type"] = "code",
            ["state"] = state
        };
        
        var queryString = string.Join("&", queryParams);
        return $"{_baseUrl}/oauth/authorize?{queryString}";
    }
    
    // 获取访问令牌    public async Task<JsonDocument> GetAccessTokenAsync(string code, string redirectUri)
    {
        var content = new FormUrlEncodedContent(new Dictionary<string, string>
        {
            ["grant_type"] = "authorization_code",
            ["client_id"] = _apiKey,
            ["client_secret"] = _apiSecret,
            ["code"] = code,
            ["redirect_uri"] = redirectUri
        });
        
        var response = await _httpClient.PostAsync($"{_baseUrl}/api/oauth.php", content);
        var responseString = await response.Content.ReadAsStringAsync();
        return JsonDocument.Parse(responseString);
    }
    
    // 获取用户信息    public async Task<JsonDocument> GetUserInfoAsync(string accessToken)
    {
        _httpClient.DefaultRequestHeaders.Authorization = 
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
        
        var response = await _httpClient.GetAsync($"{_baseUrl}/api/oauth.php?action=userinfo");
        var responseString = await response.Content.ReadAsStringAsync();
        return JsonDocument.Parse(responseString);
    }
}

Ruby 示例

require 'net/http'
require 'uri'
require 'json'

class JnqjOAuth
  def initialize(api_key, api_secret)
    @api_key = api_key
    @api_secret = api_secret
    @base_url = 'https://id.jnqj.net'
  end
  
  # 获取授权URL  def get_auth_url(redirect_uri, state = '')
    params = {
      'client_id' => @api_key,
      'redirect_uri' => redirect_uri,
      'response_type' => 'code',
      'state' => state
    }
    "#{@base_url}/oauth/authorize?#{URI.encode_www_form(params)}"
  end
  
  # 获取访问令牌  def get_access_token(code, redirect_uri)
    uri = URI("#{@base_url}/api/oauth.php")
    req = Net::HTTP::Post.new(uri)
    req.set_form_data(
      'grant_type' => 'authorization_code',
      'client_id' => @api_key,
      'client_secret' => @api_secret,
      'code' => code,
      'redirect_uri' => redirect_uri
    )
    
    res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(req)
    end
    JSON.parse(res.body)
  end
  
  # 获取用户信息  def get_user_info(access_token)
    uri = URI("#{@base_url}/api/oauth.php?action=userinfo")
    req = Net::HTTP::Get.new(uri)
    req['Authorization'] = "Bearer #{access_token}"
    
    res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(req)
    end
    JSON.parse(res.body)
  end
end


# Rails 完整示例class SessionsController < ApplicationController
  def new
    oauth = JnqjOAuth.new(ENV['JNQJ_API_KEY'], ENV['JNQJ_API_SECRET'])
    state = SecureRandom.hex(16)
    session[:oauth_state] = state
    redirect_to oauth.get_auth_url(callback_url, state)
  end
  
  def create
    # 验证 state    if params[:state] != session[:oauth_state]
      return redirect_to root_path, alert: 'Invalid state'
    end
    
    oauth = JnqjOAuth.new(ENV['JNQJ_API_KEY'], ENV['JNQJ_API_SECRET'])
    token_data = oauth.get_access_token(params[:code], callback_url)
    
    if token_data['success']
      session[:access_token] = token_data['data']['access_token']
      redirect_to profile_path
    else
      redirect_to root_path, alert: 'Authentication failed'
    end
  end
  
  private
  
  def callback_url
    url_for(action: 'create', only_path: false)
  end
end

Rust 示例

use reqwest;
use serde_json::Value;
use std::collections::HashMap;

pub struct JnqjOAuth {
    api_key: String,
    api_secret: String,
    base_url: String,
}

impl JnqjOAuth {
    pub fn new(api_key: String, api_secret: String) -> Self {
        JnqjOAuth {
            api_key,
            api_secret,
            base_url: "https://id.jnqj.net".to_string(),
        }
    }
    
    // 获取授权URL    pub fn get_auth_url(&self, redirect_uri: &str, state: &str) -> String {
        format!(
            "{}/oauth/authorize?client_id={}&redirect_uri={}&response_type=code&state={}",
            self.base_url, self.api_key, redirect_uri, state
        )
    }
    
    // 获取访问令牌    pub async fn get_access_token(&self, code: &str, redirect_uri: &str) -> Result<Value, reqwest::Error> {
        let client = reqwest::Client::new();
        let mut params = HashMap::new();
        params.insert("grant_type", "authorization_code");
        params.insert("client_id", &self.api_key);
        params.insert("client_secret", &self.api_secret);
        params.insert("code", code);
        params.insert("redirect_uri", redirect_uri);
        
        let res = client
            .post(&format!("{}/api/oauth.php", self.base_url))
            .form(¶ms)
            .send()
            .await?;
        
        res.json().await
    }
    
    // 获取用户信息    pub async fn get_user_info(&self, access_token: &str) -> Result<Value, reqwest::Error> {
        let client = reqwest::Client::new();
        let res = client
            .get(&format!("{}/api/oauth.php?action=userinfo", self.base_url))
            .bearer_auth(access_token)
            .send()
            .await?;
        
        res.json().await
    }
}

错误码

常见错误信息

安全建议

回调地址白名单

为了防止恶意应用滥用您的API密钥，强烈建议配置回调地址白名单：

• 在API密钥管理页面配置允许的回调地址
• 只添加您实际使用的域名或IP地址
• 生产环境建议使用HTTPS域名
• 本地开发可以使用127.0.0.1或localhost
• 支持企业账号添加内网IP+端口到白名单（需审核）

通用安全建议

• 使用HTTPS协议进行所有API调用
• 妥善存储API Secret，建议使用环境变量或密钥管理服务
• 实现适当的访问令牌刷新机制
• 验证state参数以防止CSRF攻击
• 定期检查API使用日志，发现异常及时处理
• 所有cURL请求启用SSL证书验证（CURLOPT_SSL_VERIFYPEER=true, CURLOPT_SSL_VERIFYHOST=2）
• client_secret 不通过GET参数传输，使用POST请求体或Authorization头
• 了解各端点的速率限制，避免触发限流
• 敏感图片（身份证等）需通过HMAC签名URL访问，有效期仅5分钟

常见问题

Q: 授权码有效期是多久？

A: 授权码有效期为10分钟，且只能使用一次。

Q: 访问令牌过期了怎么办？

A: 可以使用刷新令牌获取新的访问令牌，无需用户再次授权。

Q: 刷新令牌也过期了怎么办？

A: 需要重新引导用户进行授权流程。

Q: 如何获取用户的手机号？

A: 出于隐私保护，金牛ID不提供用户手机号获取接口。

Q: 为什么提示"回调地址不在允许的域名/IP列表中"？

A: 为了安全起见，金牛ID要求所有回调地址必须在白名单中注册。请前往API密钥管理页面，在"回调地址白名单"部分添加您的回调地址。

Q: 如何配置本地开发环境的回调地址？

A: 在回调地址白名单中添加：

• IP格式：127.0.0.1或127.0.0.1:8080（带端口）
• 域名格式：localhost

Q: 通配符域名如何使用？

A: 出于安全考虑，金牛ID回调地址采用精确匹配，不再支持通配符域名。请将每个需要使用的回调地址逐一添加到白名单中，例如app.example.com、api.example.com需分别添加。

Q: 配置白名单后多久生效？

A: 配置立即生效，无需等待。