清北CDN

Appearance

思刻通行证 ​

由清北科技、IURT、思刻协会共同开发的 OAuth SSO 平台。

1/ 申请 API ​

参考接口鉴权，申请通行证应用，设置完毕后可获得：

  • api_id：类似于公钥，应用 ID，用于区分不同应用；
  • api_key：类似于私钥，用于服务端在收到回调后与通行证服务器通信。

在调用时需按说明传入需要的 API 参数。

2/ 接入 ​

2.1/ 接入方式 ​

本通行证支持两种使用方式：

  • 完全嵌入：如果使用的网站程序支持（例如：IURT 官网，可以使用通行证作为唯一的登录方式；
  • 插件嵌入：如果网站程序自带用户系统（例如：清北博客，可以对接通行证 API，允许绑定现有的账号，此时应该以用户数据中的email字段识别和绑定用户。如果你使用 Typecho，可以使用我们开发的插件：SckurPassport。

2.2/ 登录页面 ​

在页面中使用：

html
<a href="https://passport.sckur.com/login.php?callback=YOUR_CALLBACK&api_id=YOUR_API_ID">
    <img style="height:30px" src="https://passport.sckur.com/static/images/login.png" alt="使用思刻通行证登录">
</a>
<a href="https://passport.sckur.com/login.php?callback=YOUR_CALLBACK&api_id=YOUR_API_ID">
    <img style="height:30px" src="https://passport.sckur.com/static/images/login.png" alt="使用思刻通行证登录">
</a>

回调地址需要包含http://或https://。

示例：

使用思刻通行证登录

图片大小可自行调整，注意替换回调地址和 API ID，例如使用 PHP 输出网页：

php
<?php

// 配置通行证公钥和回调地址
$callback = "https://callback.com";
$app_id = "xxxxxx";

// 输出原生账号登录表单
outputLoginPage();

// 输出第三方登录按钮
echo '<p>&bull;或使用&bull;</p>';
echo '<a href="https://passport.sckur.com/login.php?callback='.$callback.'&api_id='.$app_id.'"><img style="height:50px" src="https://passport.sckur.com/static/images/login.png" alt="使用思刻通行证登录"></a>';
<?php

// 配置通行证公钥和回调地址
$callback = "https://callback.com";
$app_id = "xxxxxx";

// 输出原生账号登录表单
outputLoginPage();

// 输出第三方登录按钮
echo '<p>&bull;或使用&bull;</p>';
echo '<a href="https://passport.sckur.com/login.php?callback='.$callback.'&api_id='.$app_id.'"><img style="height:50px" src="https://passport.sckur.com/static/images/login.png" alt="使用思刻通行证登录"></a>';

2.3/ 登录回调 ​

用户登录成功跳转到回调地址后，回调地址会收到 GET 参数refresh_token。

refresh_token可作为该唯一识别码，是获取该用户数据的凭证，过期时间五分钟。

收到回调后，使用api_key和refresh_token向 API 接口地址：

html
https://passport.sckur.com/api/
https://passport.sckur.com/api/

发起 GET/POST 请求获取数据。

PHP 代码示例：

php
<?php

function loginCallback($status, $response) {
    if ($status) {
        // 处理登录成功
    }
    else {
        // 处理登录失败
    }
}

// 应用私钥
$api_key = 'yyyyyyy';

// 回调 Token
$refresh_token = $_GET['refresh_token'];

// API 操作名称
// 参考下文中操作类型的说明
$action = 'get-maininfo';

// API 接口地址
$url = 'https://passport.sckur.com/api/'.$action.'/?site_key='.$api_key.'&user_key='.$refresh_token;

// 发起请求
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
$response = curl_exec($curl);

// 判断状态
if ($response === FALSE) {
    loginCallback(FALSE, array('msg' => curl_error($curl))); // 请求失败，返回错误信息
} elseif ($response['code'] == 200) {
    loginCallback(TRUE, $response['data']); // 登录成功，返回响应数据
else {
   loginCallback(FALSE, $response['msg']); // 登录失败，返回错误信息
}

// 结束请求
curl_close($curl);
<?php

function loginCallback($status, $response) {
    if ($status) {
        // 处理登录成功
    }
    else {
        // 处理登录失败
    }
}

// 应用私钥
$api_key = 'yyyyyyy';

// 回调 Token
$refresh_token = $_GET['refresh_token'];

// API 操作名称
// 参考下文中操作类型的说明
$action = 'get-maininfo';

// API 接口地址
$url = 'https://passport.sckur.com/api/'.$action.'/?site_key='.$api_key.'&user_key='.$refresh_token;

// 发起请求
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
$response = curl_exec($curl);

// 判断状态
if ($response === FALSE) {
    loginCallback(FALSE, array('msg' => curl_error($curl))); // 请求失败，返回错误信息
} elseif ($response['code'] == 200) {
    loginCallback(TRUE, $response['data']); // 登录成功，返回响应数据
else {
   loginCallback(FALSE, $response['msg']); // 登录失败，返回错误信息
}

// 结束请求
curl_close($curl);

操作类型：

  1. get-maininfo：获取 JSON 格式的用户主要数据，返回数据说明：
字段名说明示例
status请求执行的状态successful
id用户id1
username用户名admin
nickname用户昵称Administrator
email用户邮箱[email protected]
phonenumber用户手机号+86.18888888888
head_picture用户头像https://gravatar.com/xxx

WARNING

并不是所有应用在获取信息时都能获取所有信息，申请应用时需要勾选所需信息，在获取信息时只会返回这些授权获取的信息，因此需要进行逻辑判断，否则可能会出现获取到null或undefined等数据。

  1. get-otherinfo：获取 JSON 格式的用户其他数据。字段值全部使用 Base64 编码，因此获取后需要自行接码。返回数据说明（示例已 Base64 解码）：
字段名说明示例
introduce个人介绍思刻协会创始人
level思刻协会等级114514
invitation-code邀请码null
inbound-time加入时间2023-01-01
goal目标发展协会
label标签IURT,数学,Wikist,思刻协会
age年龄18
location地址China
gender性别male
birthday生日2022-01-01
certify认证思刻协会官方认证
hobby爱好计算机科学
institution教育经历清华大学 本科
employment职业学生
website网站https://www.sckur.com
facebookFacebook 账号@Sckur
twitterTwitter 账号@Sckur
dribbbleDribbble 账号@Sckur
whatsappWhatsApp 账号@Sckur
instagramInstagram 账号@Sckur
qqQQ 号0000000
wechat微信号sckur
telegramTelegram 账号@Sckur
githubGitHub 账号@Sckur
googleGoogle 账号[email protected]
youtubeYouTube 账号@Sckur

TIP

如果 Base64 解码时出现乱码，可以使用以下示例代码（以 PHP 为例）：

php
base64_decode(str_replace(' ','+',$response));
base64_decode(str_replace(' ','+',$response));

  1. get-oneinfo：获取 JSON 格式的单个信息，使用fieldname参数传入需要的信息字段。返回格式和编码同上。

  2. update-oneinfo：更新某个信息，使用fieldname参数传入字段名和text参数传入字段值。暂不支持批量修改，如有需要应按顺序依次修改。

WARNING

需要对text参数进行 Base64 编码，否则更新后解码会出现null或空值等异常结果。本 API 需要管理员权限。

3/ 错误码 ​

以下是已知错误：

Your API KEY does not exist!

问题原因：传入了错误的api_key。

解决方法：检查你的输入或复制，注意不要弄混api_key和api_id。

Your API status is inactive!

问题原因：你的应用状态处于非活跃状态（INACTIVE），可能由于风控被封禁，也可能因为违规使用而强制关闭。

解决方法：在应用中心申诉。

Your API has expired!

问题原因；你的应用已经过期。

解决方法：在应用中心重新申请或续期。

We do not get the website private key or the user private key or request!

问题原因：你的请求 URL 中缺少参数，如api_key/request，或者 Refresh Token 是无效值，找不到对应的用户。

解决方法：检查请求参数。

Only APIs with admin privileges can modify secondary user information!

问题原因：你的请求需要有管理员（admin）权限。

解决方法：目前而言，只有和思刻协会建立合作或加盟关系的组织（例如：清北科技、IURT）才有机会申请获得管理员权限。

If there is no correct and valid request, please refer to the API documentation!

问题原因：请求不合法，可能是请求参数、请求方式等不正确。

解决方法：按照 API 文档检查调用代码。

Refresh Token is not valid or has expired or is too early!

问题原因：Refresh Token 不正确、已过期或尚未生效。

解决方法：如果用户正常登录使用遇到这个错误，请在代码逻辑中处理此情况的办法：告知用户需要重试登录以获取正确的 Refresh Token。如果你试图重放请求，也可能会遇到这个错误。

如果出现了未知错误：

没有报错，但输出null、false

按照 API 文档检查调用代码，如果仍然报错，请到支持社区提问。提问前请务必阅读提问的智慧。