1、吉大正元身份认证 CA集中认证应用接入培训教材Version 2.7中国北京市海淀区知春路 113号银网中心 B座 2层电话：86-010-62618866 传真：86-010-82610068吉大正元信息技术股份有限公司XX产品安装手册目录1 引言 .11.1 服务概述 .11.2 适用网关版本 .12 认证原理 13 通信报文 23.1 承载协议 .23.2 认证原文产生服务报文 .23.2.1 请求报文说明 .23.2.2 响应报文说明 .23.3 认证服务报文 .33.3.1 请求报文说明 .33.3.2 响应报文说明 .53.4 标准报文示例 .73.4.1 认证原文产生服务请求报文
2、示例 .73.4.2 认证原文产生服务响应报文示例 .73.4.3 认证服务请求报文示例 .73.4.4 认证服务响应报文示例 .84 应用改造流程 94.1 第一步：客户端请求认证原文 .94.2 第二步：服务端请求认证原文 .94.3 第三步：网关返回认证原文 .104.4 第四步：服务端返回认证原文 .104.5 第五步：客户端认证 .104.6 第六步：应用服务端认证 .104.7 第七步：网关返回认证响应 .104.8 第八步：服务端处理 .10XX产品安装手册1 引言1.1 服务概述集中认证服务是吉大正元身份认证网关 I（以下简称网关）面向各种应用系统提供的一种统一的、高强度的身份
3、认证服务。通过集中认证服务应用系统可以将用户的身份凭据（证书或用户名/口令）提交给网关，网关对用户的身份凭据进行认证，认证后将认证结果、用户的身份信息及用户的属性信息返回给应用系统。集中认证服务保证了众多应用系统之间认证的权威性、安全性、用户身份的唯一性，避免了因在不同的应用系统中存在多重用户身份信息而难以管理的问题。1.2 适用网关版本本文档所描述的集中认证应用接入改造方法适用于 I2.2.2 版本。2 认证原理集中认证服务以基于 X509 证书的身份认证机制取代应用系统中原有的基于用户名/口令的传统身份认证机制。集中认证服务实际上包含两个服务：认证原文产生服务和认证服务，认证也分为两个过程
4、：请求认证原文和请求身份认证。应 用 系 统 网 关请求认证原文请求身份认证第一个过程是为了拿到网关提供的认证原文，当用户使用应用系统的客户端程序登录应用服务器时，首先由应用系统的客户端发起，应用客户端先向应用服务端请求认证原文（该认证原文用来生成后面认证服务要用到的认证请求包） ，应用服务端收到请求后发出请求向网关请求认证原文，网关收到请求后会产生认证原文并将原文返回给应用服务端，应用服务端再将原文返回给应用客户端，应用客户端拿认证原文第一个过程结束。应 用 系 统客 户 端应 用 系 统服 务 端网 关请求认证原文 请求认证原文第二个过程是进行身份认证，应用客户端拿到原文后会弹出一个对话框
5、让用户选择要用来进行身份认证的证书，用户指定证书后应用客户端使用认证原文和用户证书产生认证请求包发给应用服务端，应用服务端收到认证请求包后向网关发起身份认证请求，网关收到请求后根据认证请求包中的内容对用户身份进行认证，认证成功后网关会将认证结果和用户的属性信息返回给应用服务端，应用服务端根据这些信息可以对用户的登录请求做出回应。如果网关对用户进行身份认证时失败，则会向应用服务端返回错误信息，应用服务端可以对这些错误信息加以处理，例如：将信息返回给客户端显示，提示用户重新登录等。应 用 系 统客 户 端应 用 系 统服 务 端网 关认证请求包 请求身份认证XX产品安装手册3 通信报文集中认证服务
6、支持明文、密文（SSL）两种通讯模式，承载协议采用 http 协议，业务通信报文采用 XML 格式，分为报文头和报文体两部分内容。报文头存放通用信息，如服务类型、版本等信息；报文体存放业务数据。3.1 承载协议集中认证服务采用标准的 http 协议作为通讯承载协议，下面示例中蓝色部分需要应用系统根据实际环境调整。1. 请求协议格式范例：POST uri HTTP/1.1Accept-Language: zh-cnContent-Type: text/plainAccept-Encoding: gzip, deflateHost: ip：portContent-Length: 发送数据长度Con
7、nection: Keep-AliveCache-Control: no-cache2. 响应协议格式范例：HTTP/1.1 200 OKServer: Apache-Coyote/1.1Content-Type: text/xml;charset=UTF-8Content-Length: 回应数据长度Date: Wed, 08 Jul 2009 02:11:07 GMT3.2 认证原文产生服务报文3.2.1 请求报文说明请求报文分为报文头和报文体，报文头由版本信息和服务类型两部分组成，报文体中是应用标识。3.2.1.1 报文头1.0OriginalService version：报文版本信息
8、。 servicetype：服务类型，网关会根据服务类型指定的服务将请求分发给该服务。3.2.1.2 报文体testApp appid：应用系统在网关注册的应用标识，网关收到请求时会检查应用标识是否已经在网关注册，如果未注册则拒绝处理，返回错误信息。3.2.2 响应报文说明响应报文分为报文头和报文体。报文头由版本信息、服务类型、错误信息状态和错误信息四部分组成。报文体中是认证原文。XX产品安装手册3.2.2.1 报文头1.0OriginalServicefalseMESSAGE_CODE_13001001报文解析异常 version：报文版本信息。 servicetype：服务类型，网关会根据
9、服务类型指定的服务将请求分发给该服务。 messageState：表示业务是否出现异常情况。 “true”表示出现了异常。当值为“true”时，“messageCode”和“messageDesc”结点会给出错误代码及描述；“false”表示业务正常。无“messageCode”和“messageDesc”结点。 messageCode：错误代码 messageDesc：错误描述3.2.2.2 报文体kr5wEimbU8 original：认证原文。3.3 认证服务报文3.3.1 请求报文说明请求报文分为报文头和报文体。报文头由版本信息和服务类型两部分组成。报文体由应用信息、身份信息、访问控制
10、请求状态、用户属性请求列表四部分组成。3.3.1.1 报文头完整的请求报文头内容如下：1.XAuthenService version：报文版本信息。标准的 BS 应用系统和已经具有会话管理的 CS 应用系统改造时，客户端到应用服务器申请原文，版本号为 1.0；没有会话管理的 CS 应用系统和没有服务端的 CD（客户端/数据库）应用系统改造时，客户端到网关申请原文，版本号为 1.1。 servicetype：服务类型， AuthenService，表示请求的是集中认证服务。两个节点的内容在报文中固定不变。3.3.1.2 报文体典型的请求报文体内容如下：xxx.xxx.xxx.xxxtestAp
11、pXX产品安装手册XXXXXXXXXXXXXXadmin passwordtrue3.3.1.2.1 clientInfo 节点xxx.xxx.xxx.xxx clientInfo：客户端信息结点，该节点下可以添加任意的客户端信息。 clientIP：客户端 IP 地址。3.3.1.2.2 appId 节点testApp appId：应用系统在网关注册的应用标识，网关收到请求时会检查应用标识是否已经在网关注册，如果未注册则拒绝处理，返回错误信息。3.3.1.2.3 authen 节点XXXXXXXXXXXXXXadmin password authen：身份信息结点，此节点表示用户的各种身份凭
12、据信息。 authCredential：认证凭据，可以多次出现，表示用户的一种身份信息，例如：证书、用户名 /口令等。 authMode：认证方式，表示 authCredential 节点的信息需要何种认证方式进行处理，目前支持两种认证方式，即：“cert ”和“password” ，分别表示证书认证方式和口令认证方式。 detach：认证请求包，Detach 格式的认证请求包中不包含认证原文，所以需要与 节点配合使用将认证原文提交给网关。 original：网关颁发的认证原文，原文在提交认证时需经过 Base64 编码。 certInfo：X509 证书，证书在提交认证时需经过 Base64
13、 编码。 attach： 网关支持的另一种格式的认证请求包，这种格式的请求包中会包含认证原文，所以不需要像使用节点一样单独提交原文。在同一 节点下结点不能与 和结点同时使用。 username：用户名。 password：密码。XX产品安装手册3.3.1.2.4 accessControl 节点true accessControl：是否检查访问控制状态。false 表示不检查，当设置为“false”时，网关不做任何处理，响应报文中也不会有任何相关信息。true 表示检查，当设置为“true”时，网关检查用户是否允许访问此应用，并在报文中给出相应的信息。3.3.1.2.5 attributes
14、节点该节点表示应用系统需要请求的用户属性这些属性来自于用户的身份证书、UMS 和 PMS，在实际应用环境中应用系统可根据需要向网关请求用户的所有属性、指定属性或不请求属性。 attributes：用户属性请求列表 attributeType：用户属性请求类型。分为“all” 、 “portion”、 “none”。 “all”表示请求所有属性信息；“portion”表示只请求节点列表中指定的属性信息；“none ”表示不请求任何属性信息。 attr：指定要请求的某项用户属性信息，例如：X509Certificate.SubjectDN 表示请求的是用户身份证书中的主题（证书 DN）信息。 na
15、me：所请求属性的名称，可为中文。常用取值如下：证书认证时使用X509Certificate.NotBefore 证书开始生效时间X509Certificate.NotAfter 证书结束生效时间X509Certificate.SubjectDN 证书主题X509Certificate.SerialNumber 证书序列号X509Certificate.IssuerDN 证书颁发者 DN口令认证时使用UMS.UserID 用户 IDUMS.Username 用户名UMS.LogonName 用户登录名由于有部分信息是自定义属性，属性名称不确定，依实际情况而定。因此建议在调试时先将“attrib
16、uteType”的值设置为“all” ，当调试通过后，再将 “attributeType”改为“portion” 。 namespace：所请求属性的命名空间。常用取值如下（常量值，无具体含义）：证书属性命名空间：http:/ UMS属性命名空间：http:/ 响应报文说明响应报文分为报文头和报文体。报文头由版本信息、服务类型、错误信息状态和错误信息四部分组成。报文体由认证结果、访问控制结果和用户属性列表三部分组成。3.3.2.1 报文头完整的响应报文头内容如下：1.XAuthenServicefalse/true00000001报文解析异常 version：报文版本信息。XX产品安装手册 s
17、ervicetype：服务类型，网关会根据服务类型指定的服务将请求分发给该服务。 messageState：表示业务是否出现异常情况。 “true”表示出现了异常。当值为“true”时，“messageCode”和“messageDesc”结点会给出错误代码及描述；“false”表示业务正常。无“messageCode”和“messageDesc”结点。 messageCode：错误代码 messageDesc：错误描述3.3.2.2 报文体常用的响应报文体内容如下：Permit/Deny属性值属性值3.3.2.2.1 authResultSet 节点00000001证书被吊销 authRes
18、ultSet：认证结果集 allFailed：是否所有认证请求都失败。 “true”所有认证请求都失败；“false”至少有一种认证请求成功。 authResult：认证结果项 authMode：认证的方式。包括 “cert”和“password” ，各表示证书认证方式和口令认证方式。 success：认证结果。 “true”表示当前认证方式成功。 “false”表示认证失败，并出现下面两个结点。做错误提示。 authMessageCode：认证错误代码 authMessageDesc：认证错误描述3.3.2.2.2 accessControlResult 节点Permit/Deny acce
19、ssControlResult：网关根据规则对该用户计算的访问控制结果。 “Permit”表示允许访问。 “Deny”表示禁止访问。当认证请求报文中节点值为“false”时，此节点在响应报文中不出现。3.3.2.2.3 attributes 节点XX产品安装手册属性值 attributes：用户属性列表 attr：每个表示属性的定义 name：所请求属性的名称，与请求报文中相同。 namespace：所请求属性命名空间，与请求报文中相同。 parentName：所请求属性的子属性的父级名称(或 CODE)。当请求的属性有子属性时，将会返回该属性下所有相应属性。 节点值：根据“name ”和“n
20、amespace”取回的属性值(或 CODE)，如：CN=test,O=jit,C=cn。当存在多值的情况使用空格(“ ”)进行分隔，例如:123 456。3.4 标准报文示例3.4.1 认证原文产生服务请求报文示例1.0OriginalServicetestApp3.4.2 认证原文产生服务响应报文示例1.0OriginalServicefalsekr5wEimbU83.4.3 认证服务请求报文示例1.0AuthenServiceXX产品安装手册testAppMIIDiAYJKoZIhvcNAQcskBn0guQRgpOuU1c63QaB0=kr5wEimbU83.4.4 认证服务响应报文示
21、例1.0AuthenServicefalsecn=test,o=jit,c=cn北京吉大正元产品部XX产品安装手册4 应用改造流程C/S 应用改造流程应用系统在进行集中认证接入改造时需要将其原有的认证流程改造成网关集中认证业务流程，改造过程通常需要 8 个步骤。改造流程示意图如下：应用服务器应用客户端I 网关4、返回认证原文1、请求认证原文5、选择证书、产生认证请求包7 、 返回认证响应6 、 提交认证请求8 、 根据认证响应处理应用自身业务3 、 返回认证原文2 、 请求认证原文1、 客户端请求认证原文：应用客户端向应用服务端请求认证原文。2、 服务端请求认证原文：应用服务端向网关请求认证原
22、文。3、 网关返回认证原文：网关产生认证原文并返回给应用服务端。4、 服务端返回认证原文：应用服务端将认证原文返回给应用客户端。5、 客户端认证：应用客户端让用户选择证书，然后产生认证请求包并发给应用服务端发起认证请求。6、 应用服务端认证：应用服务端将请求包发给网关请求身份认证。7、 网关返回认证响应：网关完成认证请求的处理后，将认证响应返回给应用服务端。8、 服务端处理：应用服务端根据认证响应中的认证结果、用户属性等内容进行业务处理然后向客户端返回响应。4.1 第一步：客户端请求认证原文应用系统的客户端需要改造原先的认证、登录逻辑，首先要向服务端发起请求，请求认证原文。该原文是用来产生认证
23、请求包的，由网关产生并提供。此时应用系统的客户端与服务端之间的通讯方式和报文等均可依据应用系统原有的机制进行设计实现。4.2 第二步：服务端请求认证原文服务端需要改造原先的对客户端的认证、登录请求处理逻辑。此处分两种情况，第一种对于标准的 BS 应用系统和已经具有会话管理的 CS 应用系统，可以在服务端产生认证原文（认证原文可以是一段随机字符序列或以其它方式生成的字符序列） ，不用进行第二、三步改造，第二种对于没有会话管理的 CS 应用系统和没有服务端的 CD（客户端/数据库）应用系统在接到客户端的请求后，需要将自己的应用标识（应用标识是应用系统在网关注册的唯一标识）封装在认证原文产生服务的请
24、求报文中，然后将请求提交给网关请求认证原文。认证原文产生服务的请求报文请参照 3.4.1 认证原文产生服务 请求报文示例，详细说明请参照： 3.2.1 认证原文产生服务请求报文说明，在各种语言平台下的报文封装方法请参考各平台 Demo 示例代码。XX产品安装手册4.3 第三步：网关返回认证原文网关收到应用服务端的请求后产生一份认证原文，然后将其返回给应用服务端，应用服务端需要从网关的响应报文中解析得到认证原文，响应报文请参照 3.4.2 认证原文产生服务响应报文示例，详细说明请参照：3.2.2认证原文产生服务响应报文说明，在各种语言平台下的报文解析方法请参考各平台 Demo 示例代码。4.4
25、第四步：服务端返回认证原文应用系统的服务端产生原文或者得到网关返回的认证原文后，将其返回给应用客户端。这一步同第一步一样需要应用系统通过自身的通讯机制完成认证原文的传递。4.5 第五步：客户端认证应用系统的客户端收到服务端返回的认证原文后，需要改造原先与用户交互的逻辑，改为使用网关提供的认证请求包产生接口让用户选择证书，然后使用该证书和认证原文产生认证请求包，请求包产生后客户端需要再次向应用服务端发起请求，将认证请求包发给应用服务端。4.6 第六步：应用服务端认证应用系统的服务端收到客户端的认证请求后，得到认证请求包，然后将认证请求包封装到网关认证服务的请求报文中，发给网关进行认证。认证服务请
26、求报文请参照： 3.4.3 认证服务请求报文示例，详细说明请参照：3.3.1 认证服务请求报文说明，在各种语言平台下的报文封装方法请参考各平台 Demo 示例代码。4.7 第七步：网关返回认证响应网关完成认证后向应用服务端返回认证响应，认证响应包含认证结果和用户属性等信息。应用系统的服务端收到网关返回的认证响应后需要解析认证响应报文得到认证结果和用户属性等信息。应用认证服务响应报文请参照： 3.4.4 认证服务响应报文示例，详细说明请参照：3.3.2 响应报文说明，在各种语言平台下的报文解析方法请参考各平台 Demo 示例代码。4.8 第八步：服务端处理应用系统的服务端得到网关返回的认证结果和属性等信息后，就可以根据自己的业务规则进行后续处理。
