1、正ICS 35.240.01L 67广州市地方标准DB4401广州“数字教育城”接口技术规范Interface technical specifications forGuangzhou“Digital education city”2020-06-08 发布2020-07-01 实施广州市市场监督管理局发布DB4401/T 812020代替DBJ440100/T 2872017DB4401/T 812020I前言本标准按照GB/T 1.12009给出的规则起草。本标准由DBJ440100/T 2872017广州“数字教育城”接口技术规范确认转化而来，并代替DBJ440100/T 287201
2、7广州“数字教育城”接口技术规范。本标准与DBJ440100/T 2872017相比，除编辑性修改外，主要技术变化如下：“术语和定义”增加各术语对应英文；修改了起草单位名称。本标准由广州市教育局提出并归口。本标准起草单位：广州市教育信息中心（广州市电化教育馆）。本标准主要起草人：罗胜涛、秦小珊、余智德、袁方正。DBJ440100/T 2872017于2017年8月31日首次发布。DB4401/T 8120201广州“数字教育城”接口技术规范1范围本标准规定了广州“数字教育城”接口的术语和定义、接口机制、登录接口技术规范、接口数据规范以及数据服务接口规范。本标准适用于广州“数字教育城”信息系统接
3、口的规划、设计与实施，将分散、异构的应用进行整合，通过统一的访问入口，实现各种应用系统与广州“数字教育城”的无缝接入和集成，用于指导软件开发者对接入广州“数字教育城”的系统进行单点登录整合、用户账户数据同步及基础数据获取。2术语和定义下列术语和定义适用于本文件。2.1数字教育城digital education city以“一网一平台、两库四中心”（一网：广州教育科研网，一平台：广州“数字教育城”公共服务平台；两库：基础教育管理数据库、基础教育教学资源库；四中心：学生学习发展中心、社区学习交流中心、教育电子政务中心、教师学习发展中心）为主体内容，以全市中小学（含中等职业学校）教师和学生为服务对
4、象的教育信息化基础性平台。其主要服务覆盖教学与研究、学习与培训、活动与交流、资源与工具、班级空间、个人网页等方面，支持信息技术与教育教学的深度融合。2.2凭证ticket用户在通过单点登录验证后获得的信息，包含用户的基本信息，如唯一标识、登录名、有效期等，以 Ticket 表示。2.3凭证标识ticket identifier用户在通过单点登录验证后获得凭证的唯一标识。2.4单点登录single sign on是多个信息系统整合的技术手段，用户只需要登录一次就可以访问所有相互信任的应用系统。2.5伪单点登录pseudo single sign on用户访问一个应用首次登录时，伪单点系统提示输入
5、用户名和密码，并保存到数据库中，同时将用户名和密码填充到动态表单并提交。当用户再次访问该邮件系统时，伪单点登录系统将自动提交表单，实现单点登录，从而实现自动登录。2.6分发distribution数据生产者通过各种方式将数据传送到消费者的过程。3接口机制DB4401DB4401/T 81202023.1单点登录用户第一次访问应用系统，会被引导到认证系统中；根据用户提供的登录信息，认证系统进行身份校验，通过校验，返回给用户一个认证的凭据；用户带上凭据，作为认证的凭据，应用系统接受到请求后会把凭据送到认证系统进行校验，检查合法则通过校验，完成登录。3.2伪单点登录首次访问时，伪单点系统会提示输入该
6、应用系统的用户名、密码、编码方式、表单提交方式等信息，并保存到数据库中。当用户再次使用该系统时，伪单点登录系统将从系统提取用户上次保存的信息并自动提交表单，实现自动登录。3.3数据同步源用户基础信息有时间戳字段，记录数据被修改的时间，同时各子系统也存在有用户基础信息的备份，该备份也有一个时间戳。当用户用单点登录技术登录到子系统时，该用户的基础信息以及时间戳会以 XML 的形式捎带到子系统，子系统只需检查捎带过来的时间戳与备份是否一致，如果不一致，则以源系统为准进行修改。4登录接口技术规范4.1单点登录技术规范4.1.1具体机制如图 1 所示。1 登录信息6 ticket 验证2 ticket4
7、 ticket 验证用户应用系统 1应用系统 2应用系统 3认证系统用户信息3 ticket5 ticket图 1单点登录机制4.1.2当用户第一次访问应用系统 1 时，会被引导到认证系统中进行登录；根据用户提供的登录信息，认证系统进行身份校验，如通过校验，应返回给用户一个认证的凭据（ticket）；用户再访问其他应用时，将这个 ticket 带上，作为认证的凭据，应用系统接受到请求后将把 ticket 送到认证系统进行校验，检查 ticket 的合法性。如果通过校验，用户可在不用再次登录的情况下访问应用系统2 和应用系统 3。4.1.3PHP 系统单点登录示例参见附录 A，JAVA 系统单点
8、登录示例参见附录 B，C#系统单点登录规DB4401/T 8120203范示例参见附录 C。4.2伪单点登录技术规范4.2.1创建动态表单，提交用户预先录入的用户名和密码等信息，完成自动登录过程。具体流程如图 2 所示。4.2.2当用户访问一个应用，首次访问时，伪单点系统会提示输入该应用系统的用户名、密码、编码方式、表单提交方式等信息，并保存到数据库中，同时将用户名和密码填充到动态表单，创建动态表单自动提交，从而实现自动登录。当用户再次使用该系统时，伪单点登录系统将从系统提取用户上次保存的信息并自动提交表单，实现自动登录，不需再手工输入登录所需信息。业务子系统如果需要以伪单点登录形式接入教育城
9、，用户登录的页面不能含有验证码，或者单独提供一个不带验证码的登录页面，表单提交方式应为 get 或 post 方式。用户点击需伪单点的系统已设定了用户名和密码是保存用户名、密码、目标系统url、编码、表单提交方式等信息新建窗口用javascript创建表单Get or Post?以get 方式提交以post方式提交结束否图 2伪单点登录流程4.3基于捎带的时间戳同步规范4.3.1为了保持接入”数字教育城”各子系统的用户基础数据与源的一致性，可采用基于捎带的时间戳同步技术，具体流程如图 3 所示。DB4401DB4401/T 8120204用户单点登录到子系统检查源系统与目标系统的时间戳是否一致
10、？结束更新目标系统的信息，并将该条记录的时间戳设为源记录的时间戳是否图 3基于时间戳的同步方法4.3.2首先在源用户基础信息增加一个时间戳字段，记录数据被修改的时间，同时各子系统也存在有用户基础信息的备份，该备份也有一个时间戳。当用户用单点登录技术登录到子系统时，该用户的基础信息以及时间戳会以 XML 的形式捎带到子系统，子系统只需检查捎带过来的时间戳与备份是否一致，如果不一致，则以源系统为准进行修改。5接口数据规范5.1教师用户数据规范教师用户数据参数如下：a）userPersonId：身份证号；b）givenName：用户真实姓名；c）schooId：学校 ID；d）schoolName：
11、学校名称；e）userType：用户类型（teacher-教师）；f）teacherCourse：教师授课课程，一般格式为classId:0,className:二班,gradeId:0,gradeName:初二,subjectId:0,subjectName:物理；g）birthday：用户出生日期；h）sex：性别；i）userName：系统标识的用户名；j）phoneNumber：电话号码；k）email：电子邮箱；l）zone：学校所在的行政区。DB4401/T 81202055.2学生用户数据规范学生用户数据参数如下：a）givenName：用户真实姓名；b）schoolId：学校
12、ID；c）schoolName：学校名称；d）gradeId：年级 ID；e）gradeName：年级名称；f）classId：班级 ID；g）className：班级名称；h）userType：用户类型（student-学生）；i）birthday：用户出生日期；j）sex：性别；k）userPersonId：身份证号；l）studentNumber：学号；m）userName：系统标识的用户名；n）phoneNumber：电话号码；o）email：电子邮箱；p）zone：学校所在的行政区。5.3行政人员用户数据规范行政人员用户数据参数如下：a）givenName：用户真实姓名；b）user
13、PersonId：身份证号；c）schoolId：学校 ID；d）schoolName：学校名称；e）userType：用户类型（manager-行政人员）；f）birthday：用户出生日期；g）sex：性别；h）userName：系统标识的用户名；i）phoneNumber：电话号码；j）email：电子邮箱；k）zone：学校所在的行政区。6数据服务接口规范6.1获取批量用户信息接口获取批量用户信息接口见表 1。表 1项目方法描述接口名称getBatchUserInfo接口说明使用者可根据此方法，批量获取用户的属性信息DB4401DB4401/T 8120206表 1（续）项目方法描述请
14、求方式HTTP GET接口格式http 格式的 String 字符串：http:/www.gzjyc.org/getBatchUserInfo.jspx?pIndex=1&pageSize=30&userType=teacher&schoolId=440113004261输入参数1）pIndex:页码，int 类型，必填2）pageSize:一页记录数，int 类型，必填3）userType：批量获取用户类型，默认不传值-所有用户类型、student-学生、teacher-教师、manager-行政人员，String 类型，可选4）schoolId：学校 ID，String 类型，必填返回值J
15、SON 字符串，参见附录 D。注意：1）查询出来的结果值为 null 的表示该字段没有信息；2）接口调用者可以通过 result 来判断该查询是否成功，false 表示查询失败，true 表示查询成功，但是查询成功并不代表有记录数，只是单纯表示此次查询操作没有异常，如果要判断是否有记录可读则需检查 RowCount 字段；3）任何小于等于页数 1 的页数索引默认返回第一页，任何大于等于总页数的页数索引默认返回最后一页。异常1）页码格式错误，比如传入字符或者不传result:”false”,info:“页码格式不对，请输入正整数！”2）每页记录数格式错误，比如传入字符或者不传result:”fa
16、lse”,info:”每页的记录数格式不对，请输入正整数！”功能提供给第三方批量获取用户信息备注一个教师可以同时教授不同班级或科目，因此返回的 teacherCourse 有可能是个数组；如果教师还没有完善该字段，则 teacherCourse 字段为 null。6.2获取单个用户信息接口获取单个用户信息接口方法见表 2。表 2项目方法描述接口名称getUserInfo接口说明本接口可以根据用户名获取单个用户的信息请求方式HTTP GET接口格式http 格式的 String 字符串，例如：http:/www.gzjyc.org/getUserInfo.jspx?userName=zhangs
17、an输入参数1）userName：用户名，String 类型，必填DB4401/T 8120207表 2（续）项目方法描述返回值JSON 字符串，参见附录 E。注意：1）查询出来的结果值为 null 的表示该字段没有信息；2）接口调用者可以通过 result 来判断该查询的结果是否有记录，true 表示查询有结果，false 表示查询没有结果，即记录数为 0。异常一般情况下该接口没有异常返回，如果找不到查询的记录，字段 result 将被设置为 false 并且返回如下 json 字符串：result:false,data:功能提供给第三方，根据用户名获取一个用户的信息备注一个教师可以同时教授
18、不同班级或科目，因此返回的 teacherCourse 有可能是个数组；如果教师还没有完善该字段，则 teacherCourse 字段为 nullDB4401DB4401/T 8120208附录A(资料性附录)PHP 系统单点登录示例A.1首先找到 PHP 网站的总入口文件，一般是 index.php，或者程序执行必经的其他文件，在里面适当位置添加登录处理代码；A.2引入 caslogin()，验证成功后通过 getUser 函数可以获取登录用户基础数据，如下：$phpcas_path=SITE_PATH./CAS-1.3.2;/PHPCAS客户端路径$cas_host=cas.gzjyc.o
19、rg;/填写cas服务器部署的url或者ip$cas_port=443;/cas访问的端口$cas_context=cas;require_once$phpcas_path./CAS.php;phpCAS:client(CAS_VERSION_2_0,$cas_host,$cas_port,$cas_context);phpCAS:setNoCasServerValidation();/使用非SSL验证/phpCAS:setCasServerCACert(D:/zheng2.cer);/使用SSL验证phpCAS:forceAuthentication();$username=phpCAS:g
20、etUser();/获取登录后的用户名A.3通过getAttribute函数获取登录用户的其他信息，如学校、班级，存到SESSION里面如下：$_SESSIONuserContent=array();$_SESSIONuserContentuserType=phpCAS:getAttribute(userType);$_SESSIONuserContentgivenName=urldecode(phpCAS:getAttribute(givenName);$_SESSIONuserContentemail=urldecode(phpCAS:getAttribute(email);$_SESSI
21、ONuserContentschoolName=urldecode(phpCAS:getAttribute(schoolName);$_SESSIONuserContentuserName=phpCAS:getAttribute(userName);/教师用户信息需要处理课程JSON格式转换if($_SESSIONuserContentuserType=teacher)$course=urldecode(phpCAS:getAttribute(teacherCourse);$course=str_replace(",$course);$_SESSIONuserContentteach
22、erCourse=json_decode($course,true);A.4时间戳同步稍等的用户基础数据包含一个 stamp 字段，该字段为权威数据的时间戳，如果子系统的本地stamp 跟 CAS 的 stamp 不一致，说明用户数据有更新，子系统也应做相应的更新。A.5单点退出修改 PHP 项目登出代码，在登出代码引入 caslogout()，如下：$phpcas_path=SITE_PATH./CAS-1.3.2;/PHPCAS 客户端路径$cas_host=cas.gzjyc.org;/填写 cas 服务器 url 或 ip$cas_port=443;/cas 访问的端口$cas_con
23、text=cas;require_once$phpcas_path./CAS.php;phpCAS:logoutWithRedirectService(http:/121.8.98.146/sns);DB4401/T 8120209附录B(资料性附录)JAVA 系统单点登录示例B.1导入证书 ssl.crt 到 jdk 和 jre。导入到 jre：（路径根据需要修改）keytool-import-trustcacerts-alias casserver-file ssl.crt-keystore C:ProgramFilesJavajdk1.6.0_38jrelibsecuritycacert
24、s-storepass changeit导入到 jdk：keytool-import-trustcacerts-alias casserver-file ssl.crt-keystore C:ProgramFilesJavajre6libsecuritycacerts-storepass changeitB.2在 JAVA 项目的 WEB-INFlib 目录下加入 CAS 的客户端 cas-client-core-3.2.1.jar;B.3在 JAVA 项目 web.xml 文件加入以下 filter;org.jasig.cas.client.session.SingleSignOutHttp
25、SessionListenerCAS Single Sign Out Filterorg.jasig.cas.client.session.SingleSignOutFilterCAS Single Sign Out Filter/*CAS Authentication Filterorg.jasig.cas.client.authentication.AuthenticationFiltercasServerLoginUrlhttps:/cas.gzjyc.org/cas/loginrenewDB4401DB4401/T 81202010falsegatewayfalseserverName
26、http:/bottle.gzjyc.org/CAS Validation Filterorg.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFiltercasServerUrlPrefixhttps:/cas.gzjyc.org/cas/serverNamehttp:/bottle.gzjyc.org/useSessiontrueredirectAfterValidationtrueCAS HttpServletRequest Wrapper Filterorg.jasig.cas.client.util.Htt
27、pServletRequestWrapperFilterDB4401/T 8120201111CAS Assertion Thread Local Filterorg.jasig.cas.client.util.AssertionThreadLocalFilterCAS Authentication Filter/*CAS Validation Filter/*CAS HttpServletRequest Wrapper Filter/*CAS Assertion Thread Local Filter/*B.4修改JAVA项目登录验证代码；把原有登录的数据库用户名密码验证改为调princip
28、al.getName()，从CAS服务器端获取用户名,并通过本项目数据库拿到User直接session.setAttribute(user,user)登录;RequestMapping(value=/login.do,method=RequestMethod.GET)public String login(HttpServletRequest request,HttpSession session,Map map)AttributePrincipal principal=(AttributePrincipal)request.getUserPrincipal();Mapattributes=p
29、rincipal.getAttributes();String username=principal.getName();/*其它可用参数Stringemail=(String)attributes.get(email);Stringdecodeemail=URLDecoder.decode(email,UTF-8);Stringgivename=(String)attributes.get(givenName);Stringdecodename=URLDecoder.decode(givename,UTF-8);StringsystemRole=(String)attributes.get(
30、userType);Stringdecodeusertype=URLDecoder.decode(systemRole,UTF-8);Stringschoolname=(String)attributes.get(schoolName);Stringdecodeschoolname=URLDecoder.decode(schoolname,UTF-8);Stringgradename=(String)attributes.get(gradeName);Stringdecodegradename=URLDecoder.decode(gradename,UTF-8);Stringclassname
31、=(String)attributes.get(className);DB4401DB4401/T 81202012Stringdecodeclassname=URLDecoder.decode(classname,UTF-8);*/Users user=usersDao.getUser(username);session.setAttribute(user,user);returnredirect:/bottle/show.do;注：stamp，用户信息更新的时间戳，用于子应用系统与CAS系统的用户同步，如果子系统的stamp跟CAS的stamp不一致，说明用户数据有更新。则子系统也应做相应
32、的更新。B.5修改JAVA项目登出代码RequestMapping(value=/logout.do,method=RequestMethod.POST)public String logout(HttpServletRequest request,HttpSession session,Map map)session.removeAttribute(user);returnredirect:https:/cas.gzjyc.org/cas/logout;DB4401/T 8120201313附录C(资料性附录)C#系统单点登录示例C.1解压“统一身份认证平台单点登录 C#接口部署包.rar”
33、,修改 iis 的主目录，指向该目录。C.2修改 web.config，将 loginUrl 改为相应的 cas 登录验证地址。C.3 修 改 解 压 的 目 录 中 的 login.aspx.cs 文 件，修 改“private const string CASHOST=https:/cas.gzjyc.org/cas/ss;”为对应的 cas 服务器地址。/略去 CAS 登录判断，以下为 CAS 登录成功后，ticket 验证部分，从 ticket 验证返回信息即可获得用户信息ServicePointManager.ServerCertificateValidationCallback=n
34、ew System.Net.Security.RemoteCertificateValidationCallback(CheckValidationResult);string validateurl=CASHOST+serviceValidate?+ticket=+tkt+&+service=+service;StreamReader Reader=new StreamReader(new WebClient().OpenRead(validateurl);/检验 ticket 是否有效string resp=Reader.ReadToEnd();Sessionuser=getAttribu
35、te(resp,user);/获取登录用户名/以下根据返回信息构造用户信息，保存在 sessionDictionary userContent=new Dictionary();userContent.Add(userType,getAttribute(resp,userType);userContent.Add(givenName,getAttribute(resp,givenName);userContent.Add(email,getAttribute(resp,email);userContent.Add(schoolName,getAttribute(resp,schoolName)
36、;userContent.Add(userName,getAttribute(resp,userName);SessionuserContent=userContent;其中 getAttribute 定义如下：private string getAttribute(string resp,string key)NameTable nt=new NameTable();XmlNamespaceManager nsmgr=new XmlNamespaceManager(nt);XmlParserContext context=new XmlParserContext(null,nsmgr,nul
37、l,XmlSpace.None);XmlTextReader reader=new XmlTextReader(resp,XmlNodeType.Element,context);string value=null;while(reader.Read()string tag=reader.LocalName;DB4401DB4401/T 81202014if(tag=key)value=reader.ReadString();break;reader.Close();return value;注：stamp，用户信息更新的时间戳，用于子应用系统与CAS系统的用户同步，如果子系统的stamp跟C
38、AS的stamp不一致，说明用户数据有更新。则子系统也应做相应的更新。C.4退 出：修 改 logout.aspx.cs 文 件，修 改“privateconststringCASHOST=https:/cas.gzjyc.org/cas/ss;”为 对 应 的 cas 服 务 器 地 址，将“privateconststringSERVICE=“http:/192.168.1.7:8888”改为对应的服务首页地址。DB4401/T 8120201515附录D(资料性附录)获取批量用户信息接口返回值示例获取批量用户信息接口返回值示例：RowCount：944,PageCount：473,Pag
39、eSize：2，CurrentPage：10,result：true,data:user:teacherCourse:null,birthday:1997-01-01,stamp:2013-07-14 12:01:25.0,sex:女,schoolName:天河区中学,gradeId:null,userPersonId:440183199701020001,classId:null,studentNumber:440183001125200310016,givenName:张三,userType:student,gradeName:null,phoneNumber:18900001111,em
40、ail:12345678gzjyc.org,userName:张三,className:null,schoolId:44011234567,zone:天河区，user:teacherCourse:null,birthday:1997-01-01,stamp:2013-07-14 12:01:25.0,sex:男,schoolName:天河区中学,gradeId:null,userPersonId:440183199701020002,classId:null,DB4401DB4401/T 81202016studentNumber:440183001125200310020,givenName
41、:李四,userType:student,gradeName:null,phoneNumber:18900002222,email:12345678gzjyc.org,userName:李四,className:null,schoolId:44011234567,zone:天河区参数说明：a）RowCount：总记录数；b）PageCount：总页数；c）PageSize：一页记录数d）CurrentPage：当前页码；e）result：查询是否成功false-失败，true-成功；f）data：结果数据；g）user：用户信息：1）身份证号：userPersonId；2）用户真实姓名：giv
42、enName；3）性别：sex；4）出生日期：birthday；5）系统标识的用户名：userName；6）邮箱：email；7）手机号码：phoneNumber；8）学籍号：studentNumber；9）学校 ID：schoolId；10）学校名称：schoolName；11）年级 ID，学生特有字段：gradeId；12）年级名称，学生特有字段：gradeName；13）班级 ID，学生特有字段：classId；14）班级名称,学生特有字段：className；15）用户类型：userType（student学生、teacher教师、manager行政人员）；16）教师讲授课程：teac
43、herCourse；17）用户记录最近更新时间戳：stamp；18）学校所在的行政区：zone。DB4401/T 8120201717附录E(资料性附录)获取单个用户信息接口返回值示例获取单个用户信息接口返回值示例：result:true,data:teacherCourse:null,birthday:1999-01-01,stamp:2017-01-01 12:01:25.0,sex:男,schoolName:广州市五羊中学,gradeId:12,userPersonId:440183199701020002,classId:13,studentNumber:440102001016112
44、200011,givenName:张三,userType:student,gradeName:初一,phoneNumber:null,email:,userName:zhangsan,className:初一(1)班,schoolId:440104012005,zone:越秀区参数说明：a）result：查询是否成功false-查询结果为空，true-查询成功，有结果；b）data：结果数据：1）身份证号：userPersonId；2）用户真实姓名：givenName；3）性别：sex；4）出生日期：birthday；5）系统标识的用户名：userName；6）邮箱：email；7）手机号码：
45、phoneNumber；8）学籍号：studentNumber；9）学校 ID：schoolId；10）学校名称：schoolName；11）年级 ID，学生特有字段：gradeId；12）年级名称，学生特有字段：gradeName；13）班级 ID，学生特有字段：classId；DB4401DB4401/T 8120201814）班级名称,学生特有字段：className；15）用户类型：userType（student-学生、teacher-教师、manager-行政人员）；16）教师讲授课程：teacherCourse；17）用户记录最近更新时间戳：stamp；18）学校所在的行政区：zone。
