OAuth 2.0 接入指南

凌云海开发者平台基于标准 OAuth 2.0 授权码模式（Authorization Code Grant），提供安全可靠的身份验证服务。

协议概述

OAuth 2.0 授权码模式流程如下：

构建授权链接

将用户重定向到凌云海的授权页面，请求用户授权。

用户授权

用户在凌云海登录并确认授权，浏览器携带授权码回调到您的应用。

换取 Token

您的后端使用授权码向凌云海换取 Access Token。

获取用户信息

使用 Access Token 调用用户信息接口，获取用户身份。

1. 构建授权链接

将用户浏览器重定向到以下地址：

GET https://accounts.mclinyunhai.com/oauth/authorize
  ?client_id={CLIENT_ID}
  &redirect_uri={REDIRECT_URI}
  &response_type=code
  &state={RANDOM_STATE}

参数	必填	说明
client_id	是	您的应用的 Client ID
redirect_uri	是	回调地址，必须与应用注册时填写的一致
response_type	是	固定值 `code`
state	推荐	随机字符串，用于防止 CSRF 攻击，回调时会原样返回

强烈建议生成并验证 state 参数，防止跨站请求伪造攻击。

2. 处理回调

用户授权后，浏览器会重定向到您的回调地址，携带以下参数：

GET {YOUR_REDIRECT_URI}
  ?code={AUTHORIZATION_CODE}
  &state={RANDOM_STATE}

参数	说明
code	授权码，有效期 10 分钟，一次性使用
state	与授权请求时相同的 state 值，需验证一致性

如果用户拒绝授权，回调参数中会包含 error=access_denied，请妥善处理。

3. 换取 Access Token

使用授权码向凌云海服务器换取 Access Token：

POST https://api.mclinyunhai.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}

成功响应：

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

参数	说明
access_token	访问令牌，有效期 1 小时
token_type	固定值 `Bearer`
expires_in	过期时间，单位秒（3600）

4. 获取用户信息

使用 Access Token 获取已授权用户的信息：

GET https://api.mclinyunhai.com/oauth/userinfo
Authorization: Bearer {ACCESS_TOKEN}

成功响应：

{
  "sub": "10001",
  "nickname": "张三",
  "email": "zhangsan@example.com",
  "avatar": "https://accounts.mclinyunhai.com/uploads/avatars/10001.jpg"
}

字段	说明
sub	用户唯一标识（用户 ID）
nickname	用户昵称
email	用户邮箱
avatar	用户头像 URL

完整示例（PHP）

<?php
// 1. 构建授权链接
$clientId = 'your_client_id';
$redirectUri = 'https://your-app.com/callback';
$state = bin2hex(random_bytes(16));

$_SESSION['oauth_state'] = $state;

$authUrl = 'https://accounts.mclinyunhai.com/oauth/authorize?' . http_build_query([
    'client_id'    => $clientId,
    'redirect_uri' => $redirectUri,
    'response_type'=> 'code',
    'state'        => $state,
]);

header('Location: ' . $authUrl);

// 2. 回调处理
$code = $_GET['code'];
// 验证 state
if (!hash_equals($_SESSION['oauth_state'], $_GET['state'])) {
    die('CSRF 攻击检测');
}

// 3. 换取 Token
$ch = curl_init('https://api.mclinyunhai.com/oauth/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type'    => 'authorization_code',
        'code'          => $code,
        'client_id'     => $clientId,
        'client_secret' => $clientSecret,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$tokenData = json_decode(curl_exec($ch), true);

// 4. 获取用户信息
$ch = curl_init('https://api.mclinyunhai.com/oauth/userinfo');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $tokenData['access_token']],
    CURLOPT_RETURNTRANSFER => true,
]);
$userInfo = json_decode(curl_exec($ch), true);

echo '欢迎，' . $userInfo['nickname'];
?>