5 集成规范

　　5.1 单点登录

　　单点登录（SSO，Single Sign-on）是一种方便用户同时访问多个系统的技术，用户只需在登录时进行一次认证，就可以在多个具有访问权限的系统间自由访问，不必重复输入用户名和密码来确定身份。与教育e平台对接的应用系统，遵循“统一认证”架构，各类应用系统接入管理平台统一认证平台后，通过SSO服务，使用户进入对接系统时只需要一次登录认证。

　　5.1.1 集成模式

　　实现对于业务应用系统，青岛教育e平台提供的单点登录机制要能使用户只需要一次登录，即可访问授权范围内的所有系统。

　　[图片1.png]

　　5.1.2 单点登录流程

　　[图片2.png]

　　（1）用户尝试访问业务系统URL。

　　（2） WebApp1 判断当前用户是否有会话信息，如何有直接放行，如果没有生成一个 SAML 身份验证请求。SAML 请求将进行编码并嵌入到SSO 服务的网址中。

　　（3） WebApp1将重定向发送到用户的浏览器，引导用户浏览器跳转至平台认证中心。重定向网址包含应向SSO 服务提交的编码 SAML 身份验证请求。

　　（4）青岛教育e平台统一认证中心解码 SAML 请求，统一认证中心对用户进行身份验证。

　　（5）如果没有登录跳至认证登录界面，进行登录。

　　（6）用户在认证中心有会话信息，统一认证中心会生成一个 SAML 响应，其中包含经过验证的用户的用户名。按照 SAML 2.0 规范，此响应将使用统一认证中心的私钥进行数字签名。

　　（7）统一认证中心对 SAML 响应和 RelayState 参数进行编码，并将该信息返回到用户的浏览器。

　　（8） WebApp1使用统一认证中心的公钥验证 SAML 响应。如果成功验证该响应，则会将用户重定向到目标网址。

　　用户将重定向到目标网址并登录到 WebApp1。

　　5.1.3 应用程序改造说明

　　（1）业务系统提出接入青岛教育e平台申请；

　　（2）青岛教育e平台分配开发者账号

　　（3）业务系统使用开发者账号登录平台，创建应用系统，维护业务系统单点登录入口页面，并申请对接秘钥；

　　（4）业务系统应用服务器上部署安全组件、秘钥及票据解析组件；

　　（5）在系统中增加票据接收页面解析票据；

　　（6）解析成功后取用户唯一标识字段，同存储在数据库中的用户身份信息进行比对；若应用安装统一用户管理规范进行了统一用户对接，可以直接根据用户唯一标识进行权限初始化，若采用独立用户体系需判断是否是首次登录并建立关联关系。

　　5.2 OAuth2认证

　　5.2.1 集成模式

　　对第三方应用（互联网应用）或部分需用户主动授权访问的应用系统，青岛教育e平台提供OAuth2认证方式，以此方式既支持用户直接访问业务系统，也支持选择以青岛教育e平台统一身份认证中心作为第三方信任源登录。

　　[图片3.png]

　　5.2.2 认证流程

　　[图片4.png]

　　（1）用户访问对接应用系统，已登录到管理平台直接进行第5步；

　　( 2 ) 对接应用系统提示用户选择认证方式，包括应用系统本地用户登录、青岛教育e平台用户登录；

　　（3）用户选择青岛教育e平台账号登录；

　　（4）平台提供用户登录界面，并对用户进行身份认证；

　　（5）平台引导用户进行应用授权；

　　（6）用户完成应用授权；

　　（7）平台向用户返回应用授权信息；

　　（8）应用系统请求同步用户的基本信息；

　　（9）平台返回用基本资料；

　　（10）对接系统引导用户完善用户资料。

　　5.2.3 应用程序改造说明

　　（1）应用系统提出接入青岛教育e平台申请

　　（2）青岛教育e平台分配开发者账号

　　（3）应用系统使用开发者账号登录平台，创建应用系统，获取appid及秘钥。

　　（4）应用系统通过青岛教育e平台提供的appid以及密钥，按照OAuth2标准流程请求授权以及相关资源；

　　5.2.4 改造环节及示例代码

　　以J2EE项目为例说明业务系统需改造的环节和示例代码。

　　5.2.4.1 配置OAuth2认证参数

　　##应用appid

　　client_ID = 1234

　　##应用密钥

　　client_SERCRET = 67ad2626894b237fdcc2dc89ccbe1fa5

　　##回调地址，sdk读取

　　redirect_URI =

　　##应用首页，应用自己读取

　　app_URL =

　　##widget首页（地址可为空）

　　widget_URL =

　　#获取用户信息

　　baseURL =

　　#获取令牌

　　accessTokenURL =

　　#请求授权

　　authorizeURL =

　　5.2.4.2 OAuth2认证示例代码

　　（1）直接请求授权url(requestLogin)，自动跳转到平台登录页面，并且url请求中会附带回调服务url路径。

　　Oauth oauth = new Oauth();

　　java.util.Random r = new java.util.Random();

　　String state = Integer.toString(r.nextInt());

　　auth_url = oauth.authorize("code", state, forcelogin);//拼接授权url由sdk完成

　　hresponse.sendRedirect(auth_url);

　　String code = hrequest.getParameter("code");

　　if (code == null || code.isEmpty()) {

　　throw new ServletException("获取code出错");

　　}

　　HttpSession session = hrequest.getSession();

　　// 增加state参数防止跨站攻击，不支持session的需去掉

　　Object sstate = session.getAttribute(client_ID "_state");

　　String state = request.getParameter("state");

　　if (state == null || !state.equals(sstate)) {

　　throw new ServletException("跨站攻击！");

　　}

　　Oauth oauth = new Oauth();

　　// 获取accesstoken

　　AccessToken tokenObj；

　　String token = tokenObj.getAccessTokenString();

　　session.setAttribute(this.client_ID "_access_token", token);

　　// client_ID为应用ID, client_SERCRET为应用密钥

　　// 下面开始获取用户信息

　　OpenApi api = new OpenApi(this.client_ID, this.client_SERCRET);

　　api.client.setToken(token);

　　JSONObject userJsonObj = api.sendCommand("/user/get_user_Info_phone", "1.0", "get", null);

　　String status = userJsonObj.getString("status");

　　JSONObject result = userJsonObj.getJSONObject("result");

　　String error = result.getString("error");

　　if (error != null && !error.isEmpty()) {

　　throw new ServletException("获取信息出错");

　　}

　　Iterator it = result.keys();

　　Map u = new HashMap();

　　while (it.hasNext()) {

　　String key = (String) it.next();

　　u.put(key, result.get(key));

　　}

　　// 模拟登陆往session里放登陆信息

　　session.setAttribute("user", u);

　　// 调到第三方应用系统界面，视应用情况而定

　　hresponse.sendRedirect(hrequest.getContextPath() "/jsp/callindex.jsp");

　　（2）授权验证，第三方获取返回值code输入用户名密码之后点击登陆，平台会进行验证；验证通过之后，获取code，获取用户信息进行处理，然后自动跳转到回调url。

　　（3）第三方应用获取平台用户信息之后，进行相应的第三方资源访问；或者按照需求记录用户，以便下次访问能够直接访问第三方系统。

　　Oauth oauth = new Oauth();

　　java.util.Random r = new java.util.Random();

　　String state = Integer.toString(r.nextInt());

　　hrequest.getSession().setAttribute(Config.getValue("client_ID") "_state", state);

　　boolean forcelogin = false;

　　String auth_url = oauth.authorize("code", state, forcelogin);//拼接授权url由sdk完成

　　hresponse.sendRedirect(auth_url);

　　5.3 统一待办

　　5.3.1 集成模式

　　统一待办集成是指将各业务系统的待办事宜集成到平台的统一待办模块，通过点击待办事宜的链接，直接进人业务系统的功能模块处理待办任务。统一待办的集成可以方便用户查看权限范围内的待办任务，避免用户登录到各业务系统去查看，提高用户的工作效率。

　　对接应用按照待办集成接口规范将待办数据通过接口提供给平台，平台统一展示给用户。

　　5.3.2 集成要求

　　为方便用户能够直接访问到业务系统的待办任务，对接应用要先和平台做好单点登录后才可以进行功能组件

　　集成。

　　5.3.3 接口说明

　　接口认证参与OAuth2认证方式，根据平台给应用分配的appid和秘钥进行客户端认证。接口说明如下：

　　接口功能

　　创建或根据用户待办

　　url

　　https://server url/auth/oauth/createUpdateTask

　　参数

　　String XML，参数格式如下，taskxml最大支持50条。

　　 PK，非空，待办任务id,uuid唯一编号

　　非空，任务接收人用户的统一标示码;

　　非空；任务接收人姓名

　　非空;平台分配的appid

　　非空，任务发起人用户的统一标示码

　　< creatorName >非空，任务发起人姓名

　　< taskName >非空；待办业务的流程名称，如“请假申请”

　　< taskType >非空;待办业务的类型名称，如“行政审批”，如果在业务系统中没有待办类别，该值为ALLTYPE

　　< taskUrl >非空，必须为单点登录集成后的全路径

　　< detailUrl >详细信息页链接，必须为单点登录集成后的全路径。（用于给用户展示个人发起的任务的进度时，任务的链接）

　　< taskState >当前任务状态0：未办，1：已办

　　< taskCreateTime >非空;用户接受待办任务的时间

　　< taskModfiyTime >（最后一次修改时间）系统当前时间

　　返回值 String

　　http请求方式 POST

　　5.4 组件集成

　　5.4.1 集成模式

　　为方便用户定制个性化的个人工作空间，平台工作空间支持组件化方式布局呈现内容，用户可在应用商店里选择各类功能组件加入个人工作空间。对接应用也可以发布自己的工作组件到平台，方便用户使用应用。

　　5.4.2 集成要求

　　为方便用户使用，对接应用要先和平台做好单点登录后才可以进行功能组件集成。

　　5.4.3 设计原则

　　5.4.3.1 兼容性要求

　　系统采用B/S结构，要求支持当前各主流浏览器的兼容性，确保在IE8及以上、谷歌、火狐等浏览器能够正常浏览。在常用显示屏大小的情况下，有良好的显示状态，在系统要求最低分辨率以外的情况下也可以正常浏览。

　　5.4.3.2 界面风格统一性

　　在界面设计中要保持界面风格的统一性，统一性包括：使用相同的信息表现方法，如在字体，标签风格、颜色、术语、显示错误信息等方面保持一致。

　　5.4.3.3 导航定位清晰易用

　　设计时要对功能组件有清晰的功能定位，在视觉上作出合理的呈现，同时要充分考虑到用户的使用习惯。主色调不能与主题冲突。

　　5.4.4 界面结构

　　操作栏

　　内容区

　　功能组件不要单独设置标题，由平台统一添加。

　　附录1 OAuth2 API说明