OAuth 2.0 授权集成指南

概述

X-GORB OAuth 2.0 为第三方应用程序提供安全的身份验证和授权服务。本指南提供了将"使用 X-GORB 登录"功能集成到您应用程序所需的全部信息，并新增了对 Web、Windows、Mac、Android、iOS 五类平台应用的一键登录支持。

为什么选择 X-GORB OAuth？

快速开始

1. 注册您的应用程序

访问 X-GORB 开发者控制台 创建您的 OAuth 应用程序。

所需信息：

• 应用程序名称
• 主页 URL
• 回调 URL（重定向 URI）
• 应用类型与对应的平台标识
• 应用程序图标（可选，推荐提供）

审核通过后，您将收到：

• 客户端 ID（Client ID）：7d2f153dcb132991f9ae1b6610b6f279（示例）
• 客户端密钥（Client Secret）：请妥善保管，切勿在客户端代码中暴露

2. 三步集成

// 步骤1：将用户重定向至 X-GORB
$authUrl = "https://accounts.xgorb.cn/users/oauth/authorize.php";
$params = [
    'client_id'     => '您的客户端ID',
    'redirect_uri'  => 'https://yourapp.com/callback',
    'response_type' => 'code',
    'scope'         => 'openid profile email',
    'state'         => bin2hex(random_bytes(16))
];
header('Location: ' . $authUrl . '?' . http_build_query($params));

// 步骤2：处理回调，通过授权码换取令牌
$code = $_GET['code'];
$token = exchangeCodeForToken($code);

// 步骤3：获取用户信息
$user = fetchUserInfo($token['access_token']);

多平台登录新增 v22.1

开发者中心创建 / 编辑应用时，可选择应用类型（自动写入 oauth_applications.app_type），从而针对不同平台展示对应的登录接入方式。

平台类型与接入方式

平台专属字段

端点参考

授权端点

GET https://accounts.xgorb.cn/users/oauth/authorize.php

令牌端点

POST https://accounts.xgorb.cn/users/oauth/token.php
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "code": "上一步获得的授权码",
    "client_id": "您的客户端ID",
    "client_secret": "您的客户端密钥",
    "redirect_uri": "您的回调地址"
}

成功响应：

{
    "access_token": "a1b2c3d4e5f6...",
    "refresh_token": "r1e2f3r4e5s6h7...",
    "token_type": "Bearer",
    "expires_in": 3600
}

用户信息端点

GET https://accounts.xgorb.cn/users/oauth/userinfo.php
Authorization: Bearer {access_token}

成功响应：

{
    "sub": "123456789",
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "email": "john@example.com",
    "email_verified": true,
    "picture": "https://accounts.xgorb.cn/avatars/123456789.jpg",
    "updated_at": "2026-04-18T10:30:00Z"
}

可用权限范围（Scope）

默认权限范围：如果未指定权限范围，将仅授予 openid 权限。

完整集成示例

PHP（后端）

<?php
class XGORBOAuthClient {
    private $clientId; private $clientSecret; private $redirectUri;
    private $authUrl = 'https://accounts.xgorb.cn/users/oauth/authorize.php';
    private $tokenUrl = 'https://accounts.xgorb.cn/users/oauth/token.php';
    private $userInfoUrl = 'https://accounts.xgorb.cn/users/oauth/userinfo.php';

    public function __construct($clientId, $clientSecret, $redirectUri) {
        $this->clientId = $clientId; $this->clientSecret = $clientSecret; $this->redirectUri = $redirectUri;
    }
    public function getAuthorizationUrl($state = null) {
        $state = $state ?? bin2hex(random_bytes(16));
        $_SESSION['oauth_state'] = $state;
        $params = ['client_id' => $this->clientId, 'redirect_uri' => $this->redirectUri, 'response_type' => 'code', 'scope' => 'openid profile email', 'state' => $state];
        return $this->authUrl . '?' . http_build_query($params);
    }
    public function getAccessToken($code) { /* 实现省略 */ }
    public function refreshAccessToken($refreshToken) { /* 实现省略 */ }
    public function getUserInfo($accessToken) { /* 实现省略 */ }
}
?>

JavaScript（带后端代理的前端）

class XGORBOAuthClient {
    constructor(config) { this.clientId = config.clientId; this.redirectUri = config.redirectUri; }
    login() { /* 生成 state 并跳转 */ }
    async handleCallback() { /* 通过后端代理交换令牌 */ }
    isAuthenticated() { /* 检查本地存储 */ }
    logout() { /* 清除本地存储 */ }
}

Python（Flask）

import requests, secrets
from flask import Flask, redirect, request, session

@app.route('/login')
def login():
    state = secrets.token_urlsafe(16)
    session['oauth_state'] = state
    params = {'client_id': CLIENT_ID, 'redirect_uri': REDIRECT_URI, 'response_type': 'code', 'scope': 'openid profile email', 'state': state}
    return redirect(f"{AUTH_URL}?{urlencode(params)}")

@app.route('/callback')
def callback():
    # 验证 state 并交换令牌，获取用户信息
    pass

Node.js（Express）

const express = require('express');
const crypto = require('crypto');
const axios = require('axios');

app.get('/login', (req, res) => {
    const state = crypto.randomBytes(16).toString('hex');
    req.session.oauthState = state;
    const params = new URLSearchParams({ client_id, redirect_uri, response_type: 'code', scope: 'openid profile email', state });
    res.redirect(`${authUrl}?${params.toString()}`);
});

app.get('/callback', async (req, res) => {
    const { code, state } = req.query;
    // 交换令牌并获取用户信息
});

错误处理

常见错误代码

错误响应格式：

{
    "error": "invalid_grant",
    "error_description": "授权码已过期"
}