OAuth2 API参考

OAuth2 API参考文档

这是一个关于如何对接OAuth2协议的详细参考文档。

OAuth2 授权端点

授权端点

authorization_endpoint: https://id.rutno.com/rn-oauth/authorize

这是用户进行身份验证并授权客户端访问其资源的入口。用户会在此页面登录，并选择是否允许客户端访问其数据。

令牌端点

token_endpoint: https://id.rutno.com/rn-oauth/token

此端点用于将授权码（Authorization Code）交换为访问令牌（Access Token）。访问令牌是后续请求受保护资源的关键。

用户信息端点

userinfo_endpoint: https://id.rutno.com/rn-oauth/userinfo

该端点允许客户端通过访问令牌获取用户的基本信息，例如用户名、邮箱、头像等。

OAuth2 授权流程详解

1. 重定向用户到授权页面

在OAuth2中，第一步是将用户重定向到授权服务器的身份验证页面。这个页面由用户提供登录凭据，并决定是否授予客户端访问权限。

参数说明

  • response_type: 必须设置为code，表示使用授权码模式。
  • client_id: 应用程序注册后获得的唯一标识符。
  • redirect_uri: 用户授权完成后，授权服务器将用户重定向回此地址。
  • scope: 请求的权限范围，多个权限用空格分隔。例如：id account_id username email phone gender birthday avatar bio nickname region。
  • state: 随机生成的字符串，用于防止CSRF攻击。

示例代码

<?php
$params = [
    'response_type' => 'code',
    'client_id' => '67ff612d0fd27a8108a769f5415ecc27', // 替换为您的Client ID
    'redirect_uri' => 'https://picbox.rutno.com/auth', // 替换为您的回调地址
    'scope' => 'id account_id username email phone gender birthday avatar bio nickname region',
    'state' => bin2hex(random_bytes(16)) // 生成随机字符串防止CSRF攻击
];

$auth_url = 'https://id.rutno.com/rn-oauth/authorize?' . http_build_query($params);
header('Location: ' . $auth_url);
?>

注意事项

  • state 参数非常重要，必须在回调时验证其值是否与原始请求一致，以防止跨站请求伪造（CSRF）攻击。
  • redirect_uri 必须与您在OAuth2服务提供商处注册的回调地址完全匹配。

2. 处理回调，获取访问令牌

当用户完成授权后，授权服务器会将用户重定向到指定的redirect_uri，并在URL中附带一个授权码（code）和状态参数（state）。接下来需要使用授权码向令牌端点请求访问令牌。

回调处理

<?php
// 验证state参数
if ($_GET['state'] !== $_SESSION['oauth_state']) {
    die('State验证失败');
}

// 获取授权码
$code = $_GET['code'];
?>

请求访问令牌

使用授权码和客户端凭据向令牌端点发送POST请求，以换取访问令牌。

请求参数

  • grant_type: 设置为authorization_code，表示使用授权码模式。
  • code: 上一步从回调中获取的授权码。
  • redirect_uri: 必须与上一步使用的redirect_uri一致。
  • client_id: 客户端ID。
  • client_secret: 客户端密钥，用于验证客户端身份。

示例代码

<?php
$token_params = [
    'grant_type' => 'authorization_code',
    'code' => $code,
    'redirect_uri' => 'https://picbox.rutno.com/auth', // 替换为您的回调地址
    'client_id' => '67ff612d0fd27a8108a769f5415ecc27', // 替换为您的Client ID
    'client_secret' => 'YOUR_CLIENT_SECRET' // 替换为您的Client Secret
];

$ch = curl_init('https://id.rutno.com/rn-oauth/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($token_params));
$response = curl_exec($ch);
curl_close($ch);

$token_data = json_decode($response, true);
$access_token = $token_data['access_token'];
?>

注意事项

  • 访问令牌通常具有一定的有效期，过期后需要刷新。
  • 响应中可能还包含其他字段，如refresh_token，可用于刷新访问令牌。

3. 获取用户信息

获得访问令牌后，可以使用它访问用户信息端点，获取用户的基本信息。

请求方式

向用户信息端点发送GET请求，并在请求头中添加Authorization字段，格式为Bearer <access_token>。

示例代码

<?php
$ch = curl_init('https://id.rutno.com/rn-oauth/userinfo');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $access_token
]);
$response = curl_exec($ch);
curl_close($ch);

$user_info = json_decode($response, true);

// 输出用户信息
print_r($user_info);
?>

返回字段

用户信息端点返回的数据可能包括以下字段：

  • id: 用户唯一标识。
  • account_id: 账户ID。
  • username: 用户名。
  • email: 用户邮箱。
  • phone: 用户手机号。
  • gender: 性别。
  • birthday: 生日。
  • avatar: 用户头像URL。
  • bio: 用户个人简介。
  • nickname: 昵称。
  • region: 所在地区。

使用限制与注意事项

访问频率限制

每个IP每分钟最多允许60次请求。请合理控制请求频率，避免超出限制。

安全性

  • 确保client_secret的安全性，不要将其硬编码在前端代码中。
  • 在回调中严格验证state参数，防止CSRF攻击。

Scope权限

请求的权限范围（scope）决定了您可以访问的用户数据。请确保只请求必要的权限，遵循最小权限原则。

Token管理

  • 访问令牌有有效期，请妥善存储并及时刷新。
  • 刷新令牌（refresh_token）也需要安全存储，避免泄露。