1、广州“数字教育城”接口技术规范（GZJY/2.12014 ）（征求意见稿）广州市教育局编制2014年3月1关于本文档文档名称 广州“数字教育城”接口技术规范说明 本文档基于广州市教育信息中心（广州市电化教育馆）“数字教育城”二期项目提炼出的接口技术规范修改历史版本 日期 修改人 修改内容GZJY/2.1-20132013/12/30 谢嵘GZJY/2.1-2014.12014/3/20 方昆阳 修改本规范的应用范围和部分接口标准案例2范围1本部分主要用于广州“数字教育城” 信息系统规划与建设，将分散、异构的应用和信息资源进行整合，通过统一的访问入口，实现各种应用系统的无缝接入和集成。本接口规范
2、用于指导软件开发商对接入“数字教育城”的系统进行单点登录整合、用户基础数据下发及同步。本技术规范由三部分组成：（1）单点登录接入规范（2）用户基础数据下发规范（3）伪单点登录接入规范本规范适用于所有接入到广州“数字教育城” 的区域教育信息化应用系统，需要获取广州“数字教育城” 基础用户数据的所有应用，包括广州市全市性的教育信息化应用系统以及各区（县级市）自行建设的教育信息化应用系统，凡在此范围内的应用，均需要按照本规范进行开发。3术语和定义凭证：用户在通过单点登录验证后获得，包含用户的基本信息，如唯一标识、登录名、凭证的有效期等。规范文档中以Ticket表示凭证。凭证标识：用户在通过单点登录验
3、证后获得凭证的唯一标识。区域教育信息化应用系统：指以提供教育信息化服务为目的的在较大范围内（如中等以上城市或者大型城市的某个区）使用的信息化应用系统，具体包括教育管理系统，教育资源共享系统等。单点登录：2英文全称Single Sign On，简称为 SSO，是目前比较流行的企业业务整合的解决方案之一。SSO 的定义是在多个应用系统中，用户只需要登录一次就可以访问所有相互信任的应用系统。伪单点：又称模拟单点登录，应用漫游，代填口令等等。指用户访问一个应用，例如某WEB邮件，首次访问时，伪单点系统会提示输入WEB邮件的用户名和密码，并替保存到数据库中，同时将将用户名和密码填充到动态表单，使用动态生
4、成的表单提交，从而实现自动登录。当用户再次访问该邮件系统时，伪单点登录系统将自动提交表单，实现单点登录。Web Service：是指一类新型的WEB应用技术，特征在于能使得运行在不同机器上的不同应用无须借助附加的、专门的第三方软件或硬件，就可相互交换数据或集成。分发：指的是数据生产者通过各种方式将数据传送到消费者的过程。4作用通过广州“数字教育城” 接口技术规范，可以实现：（ 1）接入到教育城的所有应用系统共享用户基础数据；（2）让用户在一次输入用户名密码验证登录后，访问所有应用系统而不需要再输入用户名和密码进行验证；（3）用户在一次注销后，即可在所有应用系统实现注销。5服务逻辑5.1单点登录
5、技术机制3单点登录（Single Sign-On，SSO ）是一种统一认证和授权机制，指访问同一服务器不同应用中的受保护资源的同一用户，只需要登录一次，即通过一个应用中的安全验证后，再访问其他应用中的受保护资源时，不再需要重新登录验证。具体机制如图1所示：图1 单点登录机制当用户第一次访问应用系统1的时候，因为还没有登录，会被引导到认证系统中进行登录；根据用户提供的登录信息，认证系统进行身份效验，如果通过效验，应该返回给用户一个认证的凭据（ticket）；用户再访问别的应用的时候，就会将这个ticket带上，作为自己认证的凭据，应用系统接受到请求之后会把ticket送到认证系统进行效验，检查t
6、icket的合法性。如果通过校验，用户就可以在不用再次登录的情况下访问应用系统2和应用系统3。5.2基于捎带的时间戳同步机制为了保持接入“数字教育城”各子系统的用户基础数据与源的一致性，本规范采用了基于捎带的时间戳同步技术，具体流程如图3所示：4用户单点登录到子系统检查源系统与目标系统的时间戳是否一致 ？更新目标系统的信息 ，并将该条记录的时间戳设为源记录的时间戳结束否是图3 基于时间戳的同步方法首先在源用户基础信息增加一个时间戳字段，记录数据被修改的时间，同时各子系统也存在有用户基础信息的备份，该备份也有一个时间戳。当用户用单点登录技术登录到子系统时，该用户的基础信息以及时间戳会以XML的形
7、式捎带到子系统，子系统只需检查捎带过来的时间戳与备份是否一致，如果不一致，则以源系统为准进行修改。6单点登录接口规范6.1概述单点登录是一种统一认证和授权机制，指访问同一服务器不同应用中的受保护资源的同一用户，只需要登录一次，即通过一个应用中的安全验证后，再访问其他应用中的受保护资源时，不再需要重新登录验证。主要由统一身份认证平台和认证接口组成，其中认证接口包括：JAVA、PHP、C# ，如图4所示：5图4 统一身份认证平台具体流程如下：用户请求访问业务系统。业务系统在系统中查看是否有对应请求的有效令牌，若有，则读取对应的身份信息，允许其访问；若没有或令牌无效，则把用户重定向到统一身份认证平台
8、，并携带业务系统地址，进入第步。在统一身份认证平台提供的页面中，用户输入身份凭证信息，平台验证此身份凭证信息，若有效，则生成一个有效的令牌给用户，进入第步；若无效，则继续进行认证，直到认证成功或退出为止。图5 单点登录页面用户携带第步获取的令牌，再次访问业务系统。6业务系统获取用户携带的令牌，提交到认证平台进行有效性检查和身份信息获取。若令牌通过有效性检查，则认证平台会把令牌对应的用户身份信息返回给业务系统，业务系统把身份信息和有效令牌写入会话状态中，允许用户以此身份信息进行业务系统的各种操作；若令牌未通过有效性检查，则会再次重定向到认证平台，返回第步。通过统一身份认证平台获取的有效令牌，可以
9、在各个业务系统之间实现应用漫游。图6 单点退出页面6.2用户基础信息及同步单点登录系统在完成令牌验证后，会将用户基础信息以XML的形式传到目标子系统，具体如下表所示：属性 约束 释义 备注givenName 非空 真实姓名password 非空 用户密码，用AES加密userType 非空 用户类型，目前有五种：student，学生teacher，教师manager，行政管理人员（非授课教师）parent，家长school ，以学校ID 为用户名注册的一类账户数字教育城目前以学生、教师和行政管理人员三种角色为主phoneNumber 用户手机号码 可能为空7studentNumber 非空 学
10、生的学籍号，学生专有的属性email 邮箱 可能为空userPersonId 非空 用户身份证号，从学籍系统和工会网站导出，不保证100%准确学生的身份证号可能为空，且不一定准确birthday 非空 生日，格式：1985-03-16sex 非空 性别，只有两种情况：1.男；2.女stamp 非空 用户信息更新的时间戳，用于子应用系统与CAS系统的用户同步，如果子系统的stamp跟CAS的stamp不一致，说明用户数据有更新，则子系统也应做相应的更新。格式：2014-05-30 09:24:10.0schoolId 非空 学校ID ，如：440116100001 由广州市教育信息中心提供统一编
11、号，部分学校的编号不规则schoolName 非空 学校名称，如：广州市培正中学zone 学校所属的区，如：白云区、番禺区、从化市、增城市会有部分学校所属的区为空，主要是私立幼儿园gradeId 年级ID，与学校关联，学生专属字段，如果没有完善这个信息，可能为空学生字段gradeName 年级名称，学生专属字段，如果没有完善这个信息，可能为空学生字段classId 班级ID，与学校关联，学生专属字段，如果没有完善这个信息，可能为空学生字段className 班级名称，学生专属字段，如果没有完善这个信息，可能为空学生字段teacherCourse 教师所教班级和科目，一个json字符串数组，教师
12、才有的属性，可能为空或者,格式如下（教一门课和教多门课）：“classId“:42091,“className“:“一班“,“gradeId“:16847,“gradeName“:“高二“,“subjectId“:42091,“subjectName“:“信息技术“或者：“classId“:37681,“className“:“一班“,“gradeId“:15081,“gradeName“:“初三“,“subjectId“:37681,“subjectName“:“物理“,“classId“:37688,“className“:“八班“,“gradeId“:15081,“gradeName“:
13、“初三“,“subjectId“:37688,“subjectName“:“物理“,“classId“:37689,“className“:“九班“,“gradeId“:15081,“gradeName“:“初三“,“subjectId“:37689,“subjectName“:“物理“教师字段，获取年级、班级和学科信息时，要对该json进行解析8注：所有字段信息都已经用UTF-8进行编码，所以在客户端要对其进行解码。统一身份认证平台的用户基础数据是权威数据，各业务子系统必须保存一份用户基础数据的备份。用户登录完成后，统一身份认证平台捎带给业务子系统的用户基础数据包含一个时间戳，业务子系统必须
14、将该时间戳与本地备份进行比较，如果不一致，则更新为与权威数据一致。6.3 PHP系统单点登录规范（1）在PHP项目的目录下加入CAS 的客户端CAS-1.3.2；（2）PHP项目中添加CAS 登录处理代码，这里根据两种不同的验证模式区分，模式一是“允许匿名访问站点，手动点登录再验证单点登录”，模式二是“不允许匿名访问站点，正常访问之前必须先跳转单点登录验证”。对于模式一，采取的办法是将单点登录单独做一个登录入口链接，通常可以在原来的登录入口链接增设一个URL参数caslogin=yes进行判别，这样可以在原来的登录逻辑执行用户名密码校验前增加一个caslogin判断，决定是否通过单点登录方式校
15、验。对于模式二，采取的办法是找到PHP网站的总入口文件，一般是 index.php，或者程序执行必经的其他文件，然后在里面适当位置添加cas登录处理代码。下面是PHP单点登录验证逻辑的主要代码：$phpcas_path = SITE_PATH. “/CAS-1.3.2“; /PHPCAS客户端路径$cas_host = “cas.gzjyc.org“; /填写cas服务器部署的 url或者ip$cas_port = 443; /cas访问的端口$cas_context = “cas“;require_once $phpcas_path . /CAS.php;phpCAS:client(CAS_
16、VERSION_2_0, $cas_host, $cas_port, $cas_context);9phpCAS:setNoCasServerValidation(); /使用非SSL验证/phpCAS:setCasServerCACert(“D:/zheng2.cer“); / 使用SSL验证phpCAS:forceAuthentication();$username = phpCAS:getUser(); /获取登录后的用户名（3）通过getAttribute函数可以获取登录用户的其他信息，如学校、班级，部分信息需要使用urldecode 函数解码，如下：phpCAS:getAttribu
17、te(“userType“);urldecode(phpCAS:getAttribute(“givenName“);urldecode(phpCAS:getAttribute(“email“);urldecode(phpCAS:getAttribute(“schoolName“);phpCAS:getAttribute(“userName“);如果是教师用户，课程信息是JSON格式，需要转换成数组，如下：$usertype = phpCAS:getAttribute(“userType“);if($usertype = “teacher“) $course = urldecode(phpCAS
18、:getAttribute(“teacherCourse“);$course = str_replace(“, “, $course); /这一句是兼容性处理$_SESSION“userContent“teacherCourse“ = json_decode($course, true);（4）时间戳同步：用户基础数据包含一个stamp 字段，该字段为权威数据的时间戳，如果子系统的本地stamp 跟CAS 的stamp不一致，说明用户数据有更新，子系统也应做相应的更新。为了实现自动同步更新接入服务的本地数据库，需要在本地数据库用户表加入一个stamp 字段，该字段初始化为用户第一次在本地注册时的stamp，以后每次 CAS登录后进行本地登录前，比较该stamp字段和CAS传过来的stamp，如果不同则对本地用户数据进行同步更新。（5）单点退出在退出代码部分加入如下逻辑执行单点登录退出，如下：$phpcas_path = SITE_PATH. “/CAS-1.3.2“; /PHPCAS客户端路径$cas_host = “cas.gzjyc.org“; /填写cas服务器 url或ip$cas_port = 443; /cas访问的端口
