BOSS项目-SSO接入开发指南.doc

BOSS项目-系统安装手册Media-JGF05001/Media-JGF05002/Media-JGF05003IT Management DepartmentIT R&DBOSS项目SSO接入开发指南拟制：唐锋日期：2006-7-31审核：日期：批准：日期：文档编号：BOSS-XX-SIM-0创建日期：2006-MM-DD最后修改日期：2020-1-11版 本 号：1电子版文件名：BOSS项目-SSO接入开发指南 文档修改记录修改日期修改人修改说明版本号修改页BOSS项目-系统安装手册 第 31 页 共 31 页目 录1概述41.1SSO 应用接入41.2阅读对象42开发环境说明42.1系统要求42.2发布包目录结构及文件说明42.2.1api42.2.2conf42.2.3demo42.2.4lib43SSO Agent接入开发53.1应用插件加载器53.1.1实现接口63.1.2配置文件73.2操作员单点认证83.2.1实现接口83.2.2配置文件93.3操作员、组织数据消息同步接口103.3.1实现接口103.4应用认证接口113.4.1实现接口113.4.2应用认证配置124DEMO125使用SSO 客户端接口进行开发135.1创建SSO 客户端135.2操作员认证接口135.3数据访问接口145.4应用认证接口155.5JMS消息定义155.5.1操作员会话过期消息(SSOOperatorSessionEvent)155.5.2应用认证会话过期消息(SSOApplictionSessoinEvent)165.5.3操作员信息修改消息(SSOOperatorEvent)165.5.4组织信息修改消息(SSOOrgEvent)165.5.5应用权限更新消息(SSOAppPermEvent)161 概述1.1 SSO 应用接入SSO 系统提供提供三个主要功能： 操作员单点登录。 应用系统互信认证。 操作员、组织信息的访问和维护功能。应用接入SSO系统主要可以通过两种方式：Out-Application 及In-Application方式。Out-Application模式：这种方式通过SSO Agent 进行接入。SSO Agent 负责管理操作员的登录/退出流程，操作员在应用中的SSO 的Session管理，并具SSO Agent 负责收接应用发送过的操作员登录，退出等信息交给应用进行处理。这种方式对应用接入的开发来说，优点是开发工作量比较小，开发相对比较简单。缺点就是应用对SSO的控制比较弱。In-Application模式： 这种方式由应用通过SSO Server 接供的基本接口来控制SSO 登录退出流程。负责自己接收SSO Server 发送给应用的消息。这种方式应用可以灵活的控制SSO流程。缺点对应用的开发量比较大。1.2 阅读对象SSO接入开发人员。2 开发环境说明2.1 系统要求SSO Agent 是基于JDK1.4.2进行开发的，在tomcat4.1.30及BES6.5上测试通过2.2 发布包目录结构及文件说明SSOAgent api conf demo lib sso-agent-1.0.jar2.2.1 api该目录下保存了SSO 的 javadoc文件2.2.2 conf配置的模板文件2.2.3 demoSSO Agent 的DEMO程序 2.2.4 libSSO Agent 所依赖的jar文件 activation-1.1.jar commons-codec-1.3.jar commons-httpclient-3.0-rc4.jar commons-lang-2.1.jar commons-logging.jar concurrent-1.3.2.jar jaxen-1.1-beta-9.jar jdom-1.0.jar log4j-1.2.11.jar mail-1.4.jar stax-1.2.0_rc2-dev.jar stax-api-1.0.1.jar wsdl4j-1.5.2.jar wstx-asl-2.9.3.jar xfire-all-1.1.2.jar3 SSO Agent接入开发(Out-Application)SSO Agent的结构SSO Agent 是为了方便Web Base应用系统接入而提供的一套框架，他实现了三个主要的功能。 操作员认证1. SSO单点登录。2. 向SSO 服务器汇报应用程序中的会话最后活动时间。3. 通过JMS接收操作员退出消息。4. 在SSO不能登录应用认证1. 应用认证。2. 通过JMS接收应用Token过期的信息。3. 通过JMS接收应用权限变更的信息。4. 得到应用权限信息。组织操作员更新1. 通过JMS 接收组织或操作员信息修改。2. 通过接口或操作员组织创建及信息修改。3. 访问组织及操作员的基本信息。3.1 操作员单点认证接口操作员单点认证在SSO Agent通过Web Filter来实现，这个WEB Filter主要的功能有1. 检查操作员是否登录2. 检查URL上的Token串是否有效3. 在操作员登录后调用应用的操作员登录数据加载方法。4. 在操作员退出前调用应用的操作员数据卸载方法。5. 在SSO Server无法连接时，调用应急处理登录过滤器。3.1.1 实现接口接口名称：com.huashu.sso.api.app.OperatorAuthHandler1. resolverContext当操作员登录时，调用本方法应用可以在该方法中保存应用的数据到SSOTokenContext 中或是Session中。2. unloadContext当操作员退出时 调用本方法应用可以在该方法中除去在resolverContext 中的应用中填加到SSOTokenContext中的数据。3. isLogin 判断操作员是否在应用中已登录。4. getAppOperatorFilter 在SSO连接不上时。在SSO Agent 定了操作员登录及退出事件要执行的应用相应的方法public interface OperatorAuthHandler /* * 加载应有系统中的数据 * * param context 操作员TokenContext上下文 * param httpServletRquest Web 请求对象 */ public void resolverContext(SSOTokenContext context, HttpServletRequest httpServletRquest); /* * 卸载 * param context * param session */ public void unloadContext(SSOTokenContext context); /* * 检查应用操作员是否已经登陆 * param httpServletRquest * return */ public boolean isLogin(HttpServletRequest httpServletRquest); /* * 加载应急处理操作员过滤器，这个过滤器为应用自认证用户登陆的过滤器。 * * param servletContext * return 过滤器实例 */ public Filter getAppOperatorFilter(ServletContext servletContext);方法在操作员认证通过时被调用，应用程序可以这里将操作员的相关信息保存在Session中。方法在操作员退出时被调用，应用程序将 resolverContext中保存的对象从删除3.2 应用认证接口3.2.1 实现接口接口名称：com.huashu.sso.api.app.ApplicationAuthHandler应用认证是指两个系统间通过SSO认证的流程。SSO Agent 实现的基于HTTP 协议接口的认证。onError方法用于认证出错时,返回应用自定义的错误给客户端应用。如果本方法返回false 那么应用返回HTTP 中的状态码设为405给客户端。public interface ApplicationAuthHandler /* * 当应用认证出错时，SSO Agent 会调用本接口，给应用返回出错信息 * param request HttpServletRequest对象 * param response HttpServletResponse 对象 * return 如果应用处理了返回信息，返回true,否则返回false */public boolean onError(HttpServletRequest request, HttpServletResponse response);如果应用系统没有实现本接口，那么SSO Agent通过Http 协议返回状态码为405，认证出错。3.3 操作员、组织数据消息处理接口在SSO 服务器组织及操作员数据发生变化之后，SSO服务器发送JMS通知相关的应用。因些应用需要和JMS进行连接。SSO Agent 会负责接收消息并调用应用的更新接口。3.3.1 实现接口接口名称：com.huashu.sso.api.app.DataEventHandler应用数据更新接口，是应用负责实现修改或新建应用本地的操作员、组织数据。public interface DataEventHandler /* * 处理操作员更新事件 * * param operator */ public void onUpdateOperator(OperatorVO operator); /* * 处理操作员添加加事件 * * param operator */ public void onAddOperator(OperatorVO operator); /* * 处理操作员删除事件 * * param code */ public void onDisableOperator(String code); /* * 解禁操作员 * param code */ public void onEnableOperator(String code); /* * 处理组织更新事件 * * param org */ public void onUpdateOrg(OrganizationVO org); /* * 处理组织更新事件 * * param org 组织代码 */ public void onAddOrg(OrganizationVO org); /* * 处理组织激活事件 * * param code 组织代码 */ public void onDisableOrg(String orgCode); /* * 处理组织激活事件 * param code 组织代码 */ public void onEnableOrg(String org); /* * 处理增加应用管理员事件 * * param code 管理员 */ public void onAddAdmin(OperatorVO op); /* * 处理删除应用管理员事件 * param code 管理员 */ public void onRemoveAdmin(OperatorVO op);3.4 接口加载类接口名称：com.huashu.sso.api.app.DataEventHandler应用实现com.huashu.sso.api.app.PluginWebLoader这个接，由SSO接应用开发进行加载。public interface PluginWebLoader /* * 加载 操作员认证处理接口 * param servletContext * return */public OperatorAuthHandler loadOperatorAuthHandler(ServletContext servletContext);/* * 加载数据处理事件接口 * param servletContext * return */public DataEventHandler loadDataEventHandler(ServletContext servletContext);/* * 加载应用认证处理接口 * param servletContext * return */public ApplicationAuthHandler loadApplicationAuthHandler(ServletContext servletContext);/* * 加载应急处理操作员过滤器，这个过滤器为应用自认识的过滤器。 * param servletContext * return 过滤器实例 */public Filter loadOFilter(ServletContext servletContext);应用实现这个接口，SSO Agent 在启动时实例化这个接口，并加载插件。3.5 配置3.5.1 SSO Agent 基本配置在web应用负责启动SSO Agent 是一个WebListener ，要配置在web.xml 中。SSO_AGENT_CONFIG_NAME/WEB-INF/pertiescom.huashu.sso.agent.web.SSOAgentListener其中 context-param SSO_AGENT_CONFIG_NAME 指定了 ssoagent的配置文件路径 perites说明配置项示例值说明sso.agent.operator.enabletrue是否启用操作员单点登录sso.agent.application.enabletrue是否启用应用认证sso.agent.jms.enabletrue是否使用JMS接收消息sso.agent.appcodecoffee应用代码sso.agent.authkey5d7afb832ffbfba4fb57dfa4fba29d045d7afb832ffbfba4应用认证码sso.agent.pluginLoaderom.huashu.sso.demo.plugin.DemoWebLoader应用插件加载器。sso.agent.client.applicationAuthUrl2:8080/sso/services/appAuth应用认证接口地址sso.agent.client.dataAccessUrl2:8080/sso/services/data数据访问接口地址sso.agent.client.operatorAuthUrl2:8080/sso/services/opAuth操作员认证接口地址sso.agent.client.heartCheckerUrl2:8080/sso/services/heartCheck心跳检查接口地址3.5.2 单点登陆配置要使用单点登录的功能，需要在web.xml 配置过滤器。 SSOLoginFilter com.huashu.sso.agent.filter.OperatorFilter SSOLoginFilter *.jsp 3.5.3 应用认证配置 applicationFilter com.huashu.sso.agent.filter.ApplicationFilter applicationFilter /remote 3.5.4 日志配置SSO 中使用Log4j 做为日志的记录 应用系统如果已经使用log4j 可以将sso-agent的Logger配置文件进行合并4 使用SSO 客户端接口进行开发(In-Application)SSO Agent是基于SSO 服务提供的客户端接进行开发的。应用如果想自己实现SSO 流程也可以直接使用SSO 客户端进行开发。在这一节中我们说明如使客户SSO客户端进进行开发4.1 创建SSO 客户端SSO 客户端的接口主要包括的四个客户端程序操作员认证：实现SSO认证的接口应用认证：实现应用认证的接口数据访问：对操作员，及组织进行同步的接口SSO公用访问：SSO 服务器心跳检查的接口。使用SSOClientConfig 和 SSOClientFactory 创建客户端设置SSOClientConfig 对象中的几个属性属性名称appCode应用代码authKey应用认证码loginUrlSSO登录的URLlogoutUrlSSO退出的URLerrorPageSSO Token检查出错时的应用端的错误处理页面operatorAuthUrl操作员认证的WebService URLapplicationAuthUrl应用认证的WebService URLdataAccessUrl数据访问的WebService URLheartCheckerUrl心跳检查的WebServiceURL通过 SSOClientConfig中的 getInstance 方法直接从配置文件中生成一个SSOClientConfig实例。/加载配置文件SSOClientConfig clientConfig = SSOClientConfig.getInstance(config);/生成SSOClientFactory 实例SSOClientFactory ssoClientFactory = SSOClientFactory.getInstance(clientConfig);/创建应用认证客户端 AppAuthClient appAuthClient = ssoClientFactory. createAppAuthClient();/创建操作员认证客户端OperatorAuthClient operatorAuthClient = ssoClientFactory. createAppAuthClient();4.2 操作员认证接口com.huashu.sso.agent.client.OperatorAuthClient4.2.1 方法说明方法名称方法说明方法描述auth操作员认证接口这个接口主要是提供给非Web应用使用的操作员认证接口validOpToken操作员Token校验接口这个接口用于检查SSO系统分配Token的有效性进行检查。reportTokenActive操作员活动汇报接口应用程序定时汇报在应用中的操作员的最后活动时间operatorLogout操作员退出SSO在SSO上退出登陆信息listApplication列出操作员可以访问的应用4.2.2 示例代码: 检查token代码SSOClientConfig clientConfig = SSOClientConfig.getInstance(config);SSOClientFactory ssoClientFactory = SSOClientFactory.getInstance(clientConfig);OperatorAuthClient client = ssoClientFactory.createOperatorAuthClient();/从参数中得到 Token 串String tokenStr = httpServletRequest.getParameter(SSOConstants.SSO_OPERATOR_TOKEN);/解析token对象TokenVO tokenVO = TokenUtils.decode(tokenStr,clientConfig.getAuthKey();/比较IP地址if(tokenVO.getIpAddress().equals(httpServletRequest.getRemoteAddr()sendErrorResponse(httpServletResponse,sso.ip.error);elsetry/调用接口，检验token的有效性OperatorVO operatorVO = client.validOpToken(tokenVO.getValue();/保存tokenMap tokenSessionMap = (Map) servletContext.getAttribute(tokenSessionMap);tokenSessionMap.put(tokenVO.getValue(), httpServletRequest.getSession();httpServletRequest.getSession().setAttribute(SSO_TOKEN,tokenVO) ;httpServletRequest.getSession().setAttribute(SSO_OPERATOR,operatorVO) ;httpServletResponse.sendRedirect(httpServletRequest.getParameter(SSOConstants.APP_URL_NAME);catch(SSOAgentException e)sendErrorResponse(httpServletResponse,e); 汇报Token活动时间Map tokenSessionMap = (Map) servletContext.getAttribute(tokenSessionMap);TokenActive tokenActives = new TokenActivetokenSessionMap.size(); int i =0;for (Iterator iter = tokenSessionMap.entrySet().iterator(); iter.hasNext();i+) Map.Entry element = (Map.Entry) iter.next();String token = (String) element.getKey() ;HttpSession session = (HttpSession) element.getValue();tokenActivesi = new TokenActive(token,session.getLastAccessedTime();try/调用接口，汇报token的最后活动时间OperatorAuthClient client = ssoClientFactory.createOperatorAuthClient();client.reportTokenActive(tokenActives);catch(SSOAgentException e)/. 退出SSO登录OperatorAuthClient client = ssoClientFactory.createOperatorAuthClient();TokenVO tokenVO = (TokenVO) httpServletRequest.getSession().getAttribute(SSO_TOKEN) ;tryhttpServletRequest.getSession().removeAttribute(SSO_TOKEN) ;httpServletRequest.getSession().removeAttribute(SSO_OPERATOR) ;Map tokenSessionMap = (Map) servletContext.getAttribute(tokenSessionMap);tokenSessionMap.remove(tokenVO.getValue();client.operatorLogout(tokenVO.getValue();catch(SSOAgentException e)/异常处理4.3 应用认证接口4.3.1 方法说明方法名称方法说明参数说明generatorToken生成应用间认证标志客户端生成一个认证的标志validAppToken验证应用间认证标志服务器端应用校验客户端调用的Token有效性listApplicationIPRange得到客户端应用可被访问IP列表查询出某个客户端应用充许访问的IP地址listAppicationACL得到那些应用可以被客户端访问。得到可访问应用的应用代码4.3.2 示例代码 客户端申认证标志SSOClientConfig clientConfig = SSOClientConfig.getInstance(config);SSOClientFactory ssoClientFactory = SSOClientFactory.getInstance(clientConfig);AppAuthClient client = ssoClientFactory.createAppAuthClient();String serverAppCode =test001;tryString token = client.generatorToken(serverAppCode);catch(SSOAgentException e)/ 服务端认证标志SSOClientConfig clientConfig = SSOClientConfig.getInstance(config);SSOClientFactory ssoClientFactory = SSOClientFactory.getInstance(clientConfig);AppAuthClient client = ssoClientFactory.createAppAuthClient();String serverAppCode =test001;tryappToken = client.validAppToken(token);catch(SSOAgentException e)/ 得到授权应用及访问IP try String appAcl = client.listAppicationACL(); for (int i = 0; i appAcl.length; i+) IPRangeVO ipRagnes = client .listApplicationIPRange(appAcli); applicationAgentContext.getClientAppIpRanges().put(appAcli, ipRagnes); catch (SSOAgentException e) logger.debug(e.getMessage(), e); 4.4 数据访问接口com.huashu.sso.agent.client.DataAccessClient4.4.1 操作员相关方法方法名称方法说明方法描述getOperator根据操作员SSOCODE得到操作员信息得到操作员在SSO端最新的数据listOperator得到所有操作员信息在第一次数据同通时使用listOperatorByModifyDate根据最后修改时间得到操作员信息应用端可以根据上次同步的时间，进行增量同步操作员信息时使用addOperator增加操作员在应用系统端增加SSO操作员updateOperator更新操作员在应用端增加操作员moveOperator移动操作员到一个组织下移动操作员到某个组织下。一般在更新操作员所属组织时使用updatePassword修改密码操作员更新密码接口，disableOperator禁止操作员该方法可以禁止操作员在SSO上登录enableOperator启用操作员将禁止的操作员进行维护getAppAdmin得到当前应用的系统管理员得到在SSO中被应用设为管理操作员的SSO代码4.4.2 组织相关方法方法名称方法说明方法描述getOrg根据组织SSO代码，得到组织信息得到SSO服务器端最新的组织数据listOrg所有得到组织信息得到SSO服务器所有的组织信息listOrgByModifyDate根据修改日期得到组织信息根据最后修改时间得到，这个是时间之后修改的组织数据addOrganization增加组织将增加的组织信息同步到SSOupdateOrganization更新组织信息将更新的组织信息同步到SSO中disableOrganization禁用组织enableOrganization启用组织4.4.3 示例代码 新建操作员OperatorVO operatorVO = new OperatorVO();/将应用操作员对象转换operatorVO对象operatorVO.setLoginName(appOp.getLoginName);.try client. addOperator (operatorVO); catch (DataAccessException e) / TODO Auto-generated catch blocke.printStackTrace(); 获取操作员信息try OperatorVO ops = client.listOperatorByModifyDate(new Date();for(int i=0;iops.length;i+)/同步本地操作员信息updateOrSaveOperator(ops); catch (DataAccessException e) e.printStackTrace(); 修改密码/加密密码原文String key =ssoClientConfig.getAuthKey();byte value = CryptoUtils.hexStr(key);byte result = CryptoUtils.encrypt(password.getBytes(UTF-8), value);String cryPassword = CryptoUtils.byte2HexString(result);/调用修改密码接口try client.updatePassword(0000002,cryPassword); catch (DataAccessException e) e.printStackTrace();4.5 SSO服务器活动检查接口方法名称方法说明方法描述ping检查服务器的连通状态检查网络是否连通及服务器当前是否工作正常4.6 JMS消息定义SSO系统通过JMS通知应用SSO服务器端数据的变化。主要包括了以下6中类型的消息： 操作员会话过期消息。 应用认证会话过期消息。 操作员信息修改消息。 组织信息修改消息。 应用权限更新消息。 增加应用管理员消息。4.6.1 操作员会话过期消息(SSOOperatorSessionEvent)当一个操作员的Session在SSO端过期（操作员退出，强制下线）时，SSO发送这个消息到应用。目前操作员登录事件暂不使用。应用收到这个消息后，应清除操作员在应用端的Session属性说明值范围action表示是登录还是退出100：操作员退出事件200：操作员登录事件source操作员认证TokenSSO分配的token的值4.6.2 应用认证会话过期消息(SSOApplictionSessoinEvent)应用认证会话过期的消息：当应用认证标志过期时，发送这到个消息到服务器端应用。服务器端应用收到该消息后，清除认证标志的Cache属性说明值范围action1100：应用认识标志清除事件source应用认证Token1200：应用认识标志生成事件4.6.3 操作员信息修改消息(SSOOperatorEvent)操作员信息修改消息：该消息SSO服务器端的操作员数据修改时发送这个消息。应用收到这消息后，根据对应的action值进行对应的数据修改。属性说明值范围action修改数据的类型1：新增操作员事件2：删除操作员事件3：更新操作员事件4：激活操作员事件5：禁用操作员事件source操作员SSO 代码4.6.4 组织信息修改消息(SSOOrgEvent)组织信息修改消息：该消息SSO服务器端的组织数据修改时发送这个消息。应用收到这消息后，根据对应的action值修改对应的信息。属性说明值范围action修改数据的类型10：新增组织事件20：删除组织事件30：更新组织事件40：激活组织事件50：禁用组织事件source组织SSO 代码4.6.5 应用权限更新消息(SSOAppPermEvent)应用权限更新消息：该消息在设置了应用充许访问应用发送这个消息，应用端收到这个消息后，应重新调用应用认证接口listAppicationACL或listApplicationIPRange方法，重新得到应用访问权限设置。属性说明值范围action修改数据的类型1010：增加可访问应用事件1020：删除可访问应用事件1030：更新访问策略事件source应用编号4.6.6 应用管理员设置消息 (SSOAppAdminEvent)应用管理员设置消息：该消息在SSO服务器端设置应用管理员或解除应