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