1-广东省网上办事大厅统一身份认证平台对接规范V1.0.1.doc

广东省网上办事大厅统一身份认证平台业务系统接入规范V1.0.1广东省网上办事大厅二O一四年十月目录一、 前言3二、 目标4三、 对接方案43.1. 单点登录43.1.1. 系统结构53.1.2. 集成模式53.1.3. 任务分工63.2. OAuth2认证63.2.1. 系统结构63.2.2. 集成模式73.2.3. 任务分工8四、 应用程序改造说明84.1. 单点登录集成84.2. OAuth2认证集成94.3. 用户库改造说明10五、 改造环节及示例代码说明115.1. 单点登录改造说明115.1.1. 详细流程115.1.2. 组件调用说明135.1.3. 示例代码说明135.2. OAuth2认证改造说明145.2.1. 详细流程145.2.2. 登录页面改造说明165.2.3. 组件调用说明16六、 接口及参数说明166.1. 单点登录接口说明166.1.1. 设置认证服务URL166.1.2. 获取用户信息176.2. OAuth2认证接口说明196.2.1. 获取授权码196.2.2. 获取token206.2.3. 获取用户信息21一、 前言按照关于做好全省网上办事大厅建设相关筹备工作的通知（粤办函2012369号）等相关文件及省政府推进全省网上办事大厅建设的工作部署的总体要求，构建全省统一身份认证平台，主要目的是服务于全省网上办事业务信息化发展，为省直部门业务系统、各地市分厅等各类业务系统提供“用户名/密码”普通账户和CA 账户认证服务，并提供跨域单点登录服务，逐步实现“一个账号，全省通用”，建成全省标准统一、安全可靠、互联互通、应用方便的统一身份认证应用支撑体系，全面提升省网办大厅的用户体验及安全保障能力。本规范文件按照广东省网上办事大厅工作的总体要求，指导各类业务系统建设单位开展统一认证对接工作，说明相关对接流程和步骤，提供相应服务接口及应用实例，完成各业务系统与省统一身份认证平台对接工作。二、 目标各类业务系统接入省统一身份认证平台，主要目标如下：（1）统一认证：各类业务系统通过省统一身份认证平台获取符合OAuth2认证协议的用户账户认证服务，支持省统一身份认证平台用户能够登录进入各类业务系统，实现“一个账号，全省通用”。（2）单点登录：各类业务系统按照省统一身份认证平台接入规范进行sso接口集成改造，接入到省统一身份认证平台中，通过省统一身份认证平台实现各类业务系统的单点登录服务，实现“一点登录，多点漫游”。（3）CA认证：省统一身份认证平台将接入省数字证书交叉认证平台、各市级数字证书交叉认证系统等数字证书交叉认证平台，并为业务系统提供CA账户认证服务，满足全省CA用户的统一身份认证服务。三、 对接方案根据广东省网上办事大厅统一认证建设目标，根据各类业务系统不同的对接工作内容，其相应的接入集成方式分别如下：3.1. 单点登录避免重复建设，提高使用效率，遵循“统一认证”架构，各类业务系统接入省统一身份认证平台后，通过SSO服务，使用户进入省网上办事大厅、各省直部门业务系统、地市分厅系统等业务系统办理业务时只需要一次登录认证。在用户进行单点登录之前的身份认证方式可以有多种选择，省统一身份认证平台提供多种第三方信任源进行认证，包括各省直业务部门账户系统、市级身份认证平台、以及其它第三方信任源。3.1.1. 系统结构系统建设逻辑结构如下图所示：用户通过省统一身份认证平台进行登录认证，认证通过后单点登录访问业务系统，提供统一安全登录服务，从而避免用户多次重复登录各个不同系统，实现电子政务便民的工作目标。3.1.2. 集成模式 省统一身份认证平台提供统一身份管理和认证功能，并建立与各业务系统用户关联关系，避免最终用户在多个系统中重复登录，从而有效提高用户操作的方便性，达到“统一认证、统一登录”的目标。在省统一身份认证平台统一用户访问入口的情况下，业务系统单点登录集成改造工作主要包括：1、在业务系统中部署单点登录组件，配置相应数字证书；2、在业务系统中集成单点登录接口，实现对通过省统一身份认证平台统一认证后所签发的单点登录用户信息的认证及解析；3、在业务系统数据库中增加关联字段，用于建立与省统一身份认证平台用户的关联关系；3.1.3. 任务分工 l 省统一身份认证平台系统集成商：1. 提供单点登录组件及其相应的集成操作文档；2. 协助业务系统开发商调用省统一身份认证平台统一认证服务，配合联调测试，实现安全认证登录；l 业务系统开发商：1. 业务系统开发商需要调用省统一身份认证平台的单点登录组件，修改数据库，实现单点登录服务。3.2. OAuth2认证 3.2.1. 系统结构 用户直接访问业务系统，之后选择以省统一身份认证平台作为第三方信任源登录，认证后返回至该系统，系统结构图如下：如上图所示，用户在业务系统登录页面，选择省统一身份认证平台作为第三方信任源登录，业务系统登录页面、后台程序需要进行改造，实现接受省统一身份认证平台作为第三方信任源的OAuth2认证，实现用户认证信息共享。3.2.2. 集成模式采用业务系统登录页面选择省统一身份认证平台或第三方信任源认证方式来进行用户认证，其实施步骤如下：1. 在业务系统登录页面加入省统一身份认证平台认证链接，调用省统一身份认证平台OAuth2认证接口，实现用户身份认证；2. 省统一身份认证平台提供OAuth2认证接口，供业务系统调用，实现用户身份认证信息的安全传输；3. 省统一身份认证平台和其它第三方信任源之间实现OAuth2认证，调用第三方信任源的OAuth2认证接口，实现第三方信任源的用户共享。3.2.3. 任务分工 l 省统一身份认证平台系统集成商：1. 提供OAuth2认证接口及其相应的集成操作文档；2. 协助业务系统开发商调用OAuth2认证接口认证服务，实现OAuth2认证；3. 调用其它第三方信任源Oauth2认证接口，实现省统一身份认证平台与其它第三方信任源间的OAuth2认证。l 业务系统开发商：1. 需要调用统一身份认证平台OAuth2认证接口认证服务，实现OAuth2认证；2. 增加用户数据库字段，标明认证来源、认证标识号等参数。3.3. CA认证由省数字证书交叉认证平台、市级交叉认证平台提供多家CA数字证书认证服务，并作为第三方信任源接入到省统一身份认证平台，由省统一身份认证平台统一为各业务系统提供多CA认证服务，其具体实现方案可参考上一章节的OAuth2.0认证。四、 应用程序改造说明4.1. 单点登录集成用户在省统一身份认证平台完成登录认证之后，可以直接进入业务系统办理相应的业务事项，实现“一点登录，多点漫游”的目标。具体流程如下图所示：1、 确定业务系统单点登录入口页面；2、 业务系统应用服务器上部署安全组件和票据解析组件；3、 在系统中增加票据接收页面；4、 修改票据接收页面，在票据解析成功后跳转到系统的主页；5、 解析成功后取用户唯一标识UID字段，同存储在数据库中的用户身份信息进行比对；如首次登录，可建立关联关系。4.2. OAuth2认证集成用户通过省直部门、地市分厅系统页面，选择以省统一身份认证平台进行认证，具体流程如下图：1、 在业务系统登录页面增加省统一身份认证平台入口；2、 在应用服务器上部署OAuth2认证组件；3、 在业务系统中调用用户信息获取接口；4、 接受信息成功后，跳转到业务系统页面；6、 从用户信息中取用户唯一标识UID字段，同存储在数据库中的用户身份信息进行比对；如没有，则创建新用户，如已经存在，则直接登录进入系统。4.3. 用户库改造说明业务系统实现对接功能，除调用单点登录及OAuth2认证组件实现认证改造外，还需要实现省统一身份认证平台用户信息与业务系统现有用户信息之间的关联，相应用户数据库的表结构需要相应调整，如下图：为建立关联关系，需要增加用户数据库的字段，主要包括：1、用户认证来源：该项内容用于描述用户信息的来源，通过该项内容可以判断用户信息是从哪个数据源获取；长度为100个字节；2、用户认证方式；该项内容用于描述用户当前凭证类型为证书还是用户名口令，从而在用户登录时，采用正确的认证方式；长度为40个字节；3、是否实名：该项内容用于描述用户是否通过了实名认证，通过该项内容可以给用户展现不同的业务数据内容。长度为20个字节；4、用户信息唯一标识UID：该项内容用于描述用户信息的唯一标识号，每一个标识号代表一个独立的用户。长度为32个字节。五、 改造环节及示例代码说明5.1. 单点登录改造说明5.1.1. 详细流程流程描述如下：1、 用户访问省统一身份认证平台，并输入身份认证凭证；2、 省统一身份认证平台对用户身份进行登录凭证验证；3、 由省统一身份认证平台对用户进行身份认证后，返回用户token；4、 用户选择需要业务系统；5、 省统一身份认证平台将用户token、随机数及签名形成单点登录票据，并发送给业务系统；6、 业务系统接收省统一身份认证平台单点登录票据，并对票据进行解析，获取随机数和Token，并对随机数进行签名处理；7、 业务系统将相应的随机数签名值和Token提交给省统一身份认证平台；8、 省统一身份认证平台验证用户token及随机数，获取用户UID；9、 省统一身份认证平台将用户信息（含UID等）返回给接入业务系统；10、 根据用户UID，业务系统判断用户是否有权限登录，验证通过后，用户成功登录进入业务系统。5.1.2. 组件调用说明需要在业务系统中引入BJCA-UAMS-SDK-1.0.jar，根据相应的API接口说明，调用jar包相应方法实现用户信息的获取。5.1.3. 示例代码说明业务系统验证token后，用token得到userIdCode，用于用户权限判断，代码示意如下： clientResponse = clientResource.path(identity).path(attributes).queryParam(subjectid, URLEncoder.encode(tokenId, utf-8).queryParam(attributenames, useridcode).header(Content-Type, application/json;charset=UTF-8).get(ClientResponse.class); if (clientResponse.getStatus() != 200) /判断返回结果,200为成功 request.setAttribute(error, 获取userIdCode失败！); request.getRequestDispatcher(./success.jsp).forward(request, response); return; String resultTemp = clientResponse.getEntity(String.class); String result = resultTemp.split(rn); HashMap resultMap = new HashMap(); for (int i = 0; i result.length; i+) if (resulti != null & resulti.contains() | resulti.contains(userdetails.attribute.value) if (resulti.contains() resultMap.put(resulti.substring(=.length(), resulti + 1.substring(userdetails.attribute.value=.length(); request.setAttribute(userIdCode, resultMap.get(useridcode);5.2. OAuth2认证改造说明5.2.1. 详细流程用户首次直接访问业务系统，使用省统一身份认证平台账户作为第三方信任源进行登录认证流程如下：流程描述如下：1. 用户访问接入业务系统办理相关服务事项；2. 业务系统提示用户选择账户认证方式，用户账户认证方式包括业务系统本地用户登录、第三方信任源（市级认证平台、省直部门账号系统等）用户登录；3. 用户选择省统一身份认证平台账号登录；4. 省统一身份认证平台提供用户登录界面，并对用户进行身份认证；5. 省统一身份认证平台将用户身份认证结果返回给业务系统；6. 业务系统接收用户登录状态，并判断用户是否为首次访问业务系统，若用户为首次访问，则需要用户进行应用授权；7. 业务系统请求用户进行认证账号绑定；8. 用户进行授权确认，允许业务系统使用省统一身份认证平台账号；9. 省统一身份认证平台向业务系统同步用户的基本信息资料；10. 用户登录成功，业务系统创建用户本地账户，并根据业务需求，可要求用户补充相关材料；11. 用户补充相关材料后，即可登录进入业务系统，并办理相关服务事项。5.2.2. 登录页面改造说明业务系统需修改登录页面，增加“省统一省份认证平台认证”按钮，后台配置省统一身份认证平台OAuth2认证接口。5.2.3. 组件调用说明需要在业务系统中引入相应的jar包至项目工程内，根据相应的API接口说明，调用jar包相应方法实现用户授权及用户信息的获取。六、 接口及参数说明6.1. 单点登录接口说明用户通过url获得省网办大厅用户的tokenid及随机数，调用验证随机数接口对随机数进行验证，并获取用户uid及用户的所有信息。单点登录接口主要提供如下功能：验证随机数及tokenid的有效性、获取用户相关信息。6.1.1. 设置认证服务URL服务名称Map setServerUrl(String ServerUrl)服务说明设置服务器URL，调用一次即可参数列表参数名称参数说明ServerUrl服务器URL返回值MapKey：status（错误码）Key：message（错误信息）备注返回值说明：0-成功101-服务器URL不能为空！105-服务器URL未知错误，检查服务器URL！6.1.2. 获取用户信息服务名称Map getAllUserAttributes(String tokenId, String random)服务说明获取所有用户属性参数列表参数名称参数说明tokenId登录后会话的Tokenrandom使用generateRandom函数返回的随机数返回值MapKey：status（错误码）Key：message（错误信息）Key：idcardnumber（证件号码）Key：useridcode（用户身份唯一标识码）Key：cn（用户姓名）Key：uid（用户的登录标识，值为用户登录名或证书唯一标识）Key：mail（邮件地址）Key：telephonenumber（电话号码）Key：credenceclass（用户本次登录时使用的凭证类型，Credence_001表示使用证书登录，Credence_002表示使用密码登录）Key：inetuserstatus（用户状态。Active表示状态正常，InActive表示状态非法（停用或注销）Key：extproperties（扩展属性。扩展属性内部以map的方式保存值，如果是多值，用逗号分隔。举例如下：如果扩展属性的英文名是testExt，则通过map.get(“extproperties”).get(“testExt”)获取）Key：passwordmodifieddate（密码修改日期）Key：usermodpwdflag（用户修改密码标志。0表示默认密码需要修改；1表示已经修改默认密码）createtime（创建时间）备注错误码：0-成功101-随机数已失效!102-验证Token失败！103-获取用户信息失败！104-系统内部错误！106-参数编码错误107-服务连接错误！108-用户认证失败！109-用户状态异常！110-请求地址不存在！使用此接口前需至少调用一次setServerUrl接口设置服务端URL6.2. OAuth2认证接口说明6.2.1. 获取授权码接口功能获得授权码urlhttps:/server url/oauth2/authorize参数client_id ：应用向am 预先申请的client_id scope ：app向am请求的属性，可以根据具体情况增加或者减少，中间用空格分割（URL编码后是加号）。redirect_uri ：认证完成并且用户对app授权后返回的地址，此地址可以得到grant_code授权码。response_type固定为code返回值grant_code ：授权码。获取方式，例如request.getParameter(code)http请求方式GET6.2.2. 获取token接口功能通过授权码获得访问tokenurlhttps:/server url/oauth2/access_token参数client_id ：应用向am 预先申请的client_id client_secret ：应用向am 预先申请的密钥