单点登录接口开发文档

前言

本文档针对只做单点登录、不做数据同步的平台而编写。

接入知未产品单点登录的平台需要先联系知未科技研发，获取2个基本参数：平台ID[platform]，平台密钥[key]。这两个参数也可以反过来向知未科技提供。

对接新学校的时候，双方约定[orgId]，在各自平台创建好学校。

部署好系统后会确定[serverBaseUrl]。

单点登录

第三方平台按如下方式构造知未产品（例如“成绩分析”）的入口链接：

接口说明

请求方式：GET
PC版登录URL：[serverBaseUrl]/school-users/api/pclogin?platform=[platform]&orgId=[orgId]&role=[role]&name=[name]&grade=[grade]&class=[class]&timestamp=[timestamp]&sign=[sign]
移动版登录URL：[serverBaseUrl]/school-users/api/mlogin?platform=[platform]&orgId=[orgId]&role=[role]&name=[name]&grade=[grade]&class=[class]&timestamp=[timestamp]&sign=[sign]
URL参数说明:

参数	类型	是否必填	描述
platform	string	是	平台ID
orgId	string	是	学校ID
role	string	是	角色名称：管理员、教师或学生
name	string	是	用户姓名。对于管理员，双方要约定创建这样的账号。对于有重名的教师，需要双方约定传一个别名，例如“张老师”、“张老师2”。学生通过年级和班别值来区分重名的情况。
grade	string	对于学生是，其它角色否	年级
class	string	对于学生是，其它角色否	班别
timestamp	int	是	时间戳（Unixtime），有效时长7200秒
sign	string	是	签名

签名参数sign生成说明

第一步：对传入的参数按照键名排序
第二步：使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA
第三步：在stringA最后拼接上“&key=[平台密钥]”得到stringSignTemp字符串，并对stringSignTemp进行MD5运算
第四步：得到最终请求字符串sign

PHP签名算法示例:

// $key 平台密钥
function sign($data, $key) {
  ksort($data);                                   // 正向排序
  $key_str = urldecode(http_build_query($data));  // 连接字符串
  $key_str .= '&key=' . $key;                     // 拼接key
  return md5($key_str);
}

$data = array(
   'platform' => 'testPlatform',
   'orgId' => 'testSchool',
   'role' => '教师',
   'name' => '李老师',
   'timestamp' => 1639017000,
);
$sign = sign($data, $key);

注意：timestamp的有效时间为7200秒，超过该时长请求无效，以降低受到重放攻击的风险。