吉大正元身份认证网关报文认证应用接入培训教材V270816I22.docx

1、吉大正元身份认证网关报文认证应用接入培训教材V270816I22吉大正元身份认证CA集中认证应用接入培训教材Version 2.7中国北京市海淀区知春路113号银网中心B座2层电话：86-010-62618866 传真：86-010-82610068吉大正元信息技术股份有限公司1引言1.1服务概述集中认证服务是吉大正元身份认证网关I（以下简称网关）面向各种应用系统提供的一种统一的、高强度的身份认证服务。通过集中认证服务应用系统可以将用户的身份凭据（证书或用户名/口令）提交给网关，网关对用户的身份凭据进行认证，认证后将认证结果、用户的身份信息及用户的属性信息返回给应用系统。集中认证服务保证了众多

2、应用系统之间认证的权威性、安全性、用户身份的唯一性，避免了因在不同的应用系统中存在多重用户身份信息而难以管理的问题。1.2适用网关版本本文档所描述的集中认证应用接入改造方法适用于I2.2.2版本。2认证原理集中认证服务以基于X509证书的身份认证机制取代应用系统中原有的基于用户名/口令的传统身份认证机制。集中认证服务实际上包含两个服务：认证原文产生服务和认证服务，认证也分为两个过程：请求认证原文和请求身份认证。第一个过程是为了拿到网关提供的认证原文，当用户使用应用系统的客户端程序登录应用服务器时，首先由应用系统的客户端发起，应用客户端先向应用服务端请求认证原文（该认证原文用来生成后面认证服务要

3、用到的认证请求包），应用服务端收到请求后发出请求向网关请求认证原文，网关收到请求后会产生认证原文并将原文返回给应用服务端，应用服务端再将原文返回给应用客户端，应用客户端拿认证原文第一个过程结束。第二个过程是进行身份认证，应用客户端拿到原文后会弹出一个对话框让用户选择要用来进行身份认证的证书，用户指定证书后应用客户端使用认证原文和用户证书产生认证请求包发给应用服务端，应用服务端收到认证请求包后向网关发起身份认证请求，网关收到请求后根据认证请求包中的内容对用户身份进行认证，认证成功后网关会将认证结果和用户的属性信息返回给应用服务端，应用服务端根据这些信息可以对用户的登录请求做出回应。如果网关对用户

4、进行身份认证时失败，则会向应用服务端返回错误信息，应用服务端可以对这些错误信息加以处理，例如：将信息返回给客户端显示，提示用户重新登录等。3通信报文集中认证服务支持明文、密文（SSL）两种通讯模式，承载协议采用http协议，业务通信报文采用XML格式，分为报文头和报文体两部分内容。报文头存放通用信息，如服务类型、版本等信息；报文体存放业务数据。3.1承载协议集中认证服务采用标准的http协议作为通讯承载协议，下面示例中蓝色部分需要应用系统根据实际环境调整。1.请求协议格式范例：POST uri HTTP/1.1Accept-Language: zh-cnContent-Type: text/p

5、lainAccept-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认证原文产生服务报文3.2.1请求报文说明请求报文分为报文头和报文体，报文头由

6、版本信息和服务类型两部分组成，报文体中是应用标识。3.2.1.1报文头1.0OriginalServiceversion：报文版本信息。servicetype：服务类型，网关会根据服务类型指定的服务将请求分发给该服务。3.2.1.2报文体testAppappid：应用系统在网关注册的应用标识，网关收到请求时会检查应用标识是否已经在网关注册，如果未注册则拒绝处理，返回错误信息。3.2.2响应报文说明响应报文分为报文头和报文体。报文头由版本信息、服务类型、错误信息状态和错误信息四部分组成。报文体中是认证原文。3.2.2.1报文头1.0OriginalServicefalseMESSAGE_CODE

7、_13001001报文解析异常version：报文版本信息。servicetype：服务类型，网关会根据服务类型指定的服务将请求分发给该服务。messageState：表示业务是否出现异常情况。“true”表示出现了异常。当值为“true”时，“messageCode”和“messageDesc”结点会给出错误代码及描述；“false”表示业务正常。无“messageCode”和“messageDesc”结点。messageCode：错误代码messageDesc：错误描述3.2.2.2报文体kr5wEimbU8original：认证原文。3.3认证服务报文3.3.1请求报文说明请求报文分为报

8、文头和报文体。报文头由版本信息和服务类型两部分组成。报文体由应用信息、身份信息、访问控制请求状态、用户属性请求列表四部分组成。3.3.1.1报文头完整的请求报文头内容如下： 1.X AuthenServiceversion：报文版本信息。标准的BS应用系统和已经具有会话管理的CS应用系统改造时，客户端到应用服务器申请原文，版本号为1.0；没有会话管理的CS应用系统和没有服务端的CD（客户端/数据库）应用系统改造时，客户端到网关申请原文，版本号为1.1。servicetype：服务类型，AuthenService，表示请求的是集中认证服务。两个节点的内容在报文中固定不变。3.3.1.2报文体典型

9、的请求报文体内容如下： xxx.xxx.xxx.xxx testApp XXXXXXX XXXXXXX admin password true 3.3.1.2.1clientInfo节点 xxx.xxx.xxx.xxx clientInfo：客户端信息结点，该节点下可以添加任意的客户端信息。clientIP：客户端IP地址。3.3.1.2.2appId节点testAppappId：应用系统在网关注册的应用标识，网关收到请求时会检查应用标识是否已经在网关注册，如果未注册则拒绝处理，返回错误信息。3.3.1.2.3authen节点 XXXXXXX XXXXXXX admin password au

10、then：身份信息结点，此节点表示用户的各种身份凭据信息。authCredential：认证凭据，可以多次出现，表示用户的一种身份信息，例如：证书、用户名/口令等。authMode：认证方式，表示authCredential节点的信息需要何种认证方式进行处理，目前支持两种认证方式，即：“cert”和“password”，分别表示证书认证方式和口令认证方式。detach：认证请求包，Detach格式的认证请求包中不包含认证原文，所以需要与节点配合使用将认证原文提交给网关。original：网关颁发的认证原文，原文在提交认证时需经过Base64编码。certInfo：X509证书，证书在提交认证时

11、需经过Base64编码。attach： 网关支持的另一种格式的认证请求包，这种格式的请求包中会包含认证原文，所以不需要像使用节点一样单独提交原文。在同一节点下结点不能与和结点同时使用。username：用户名。password：密码。3.3.1.2.4accessControl节点trueaccessControl：是否检查访问控制状态。false表示不检查，当设置为“false”时，网关不做任何处理，响应报文中也不会有任何相关信息。true表示检查，当设置为“true”时，网关检查用户是否允许访问此应用，并在报文中给出相应的信息。3.3.1.2.5attributes节点该节点表示应用系统需

12、要请求的用户属性这些属性来自于用户的身份证书、UMS和PMS，在实际应用环境中应用系统可根据需要向网关请求用户的所有属性、指定属性或不请求属性。 attributes：用户属性请求列表attributeType：用户属性请求类型。分为“all”、“portion”、“none”。“all”表示请求所有属性信息；“portion”表示只请求节点列表中指定的属性信息；“none”表示不请求任何属性信息。attr：指定要请求的某项用户属性信息，例如：X509Certificate.SubjectDN表示请求的是用户身份证书中的主题（证书DN）信息。name：所请求属性的名称，可为中文。常用取值如下：

13、证书认证时使用X509Certificate.NotBefore 证书开始生效时间X509Certificate.NotAfter 证书结束生效时间X509Certificate.SubjectDN 证书主题X509Certificate.SerialNumber 证书序列号X509Certificate.IssuerDN 证书颁发者DN口令认证时使用UMS.UserID 用户IDUMS.Username 用户名UMS.LogonName 用户登录名 由于有部分信息是自定义属性，属性名称不确定，依实际情况而定。因此建议在调试时先将“attributeType”的值设置为“all”，当调试通过后

14、，再将“attributeType”改为“portion”。namespace：所请求属性的命名空间。常用取值如下（常量值，无具体含义）：证书属性命名空间：UMS3.X属性命名空间：其它版本UMS属性命名空间：3.3.2响应报文说明响应报文分为报文头和报文体。报文头由版本信息、服务类型、错误信息状态和错误信息四部分组成。报文体由认证结果、访问控制结果和用户属性列表三部分组成。3.3.2.1报文头完整的响应报文头内容如下： 1.X AuthenServicefalse/true 00000001 报文解析异常version：报文版本信息。servicetype：服务类型，网关会根据服务类型指定的

15、服务将请求分发给该服务。messageState：表示业务是否出现异常情况。“true”表示出现了异常。当值为“true”时，“messageCode”和“messageDesc”结点会给出错误代码及描述；“false”表示业务正常。无“messageCode”和“messageDesc”结点。messageCode：错误代码messageDesc：错误描述3.3.2.2报文体常用的响应报文体内容如下： Permit/Deny 属性值属性值 3.3.2.2.1authResultSet节点 00000001 证书被吊销 authResultSet：认证结果集allFailed：是否所有认证请求

16、都失败。“true”所有认证请求都失败；“false”至少有一种认证请求成功。authResult：认证结果项authMode：认证的方式。包括“cert”和“password”，各表示证书认证方式和口令认证方式。success：认证结果。“true”表示当前认证方式成功。“false”表示认证失败，并出现下面两个结点。做错误提示。authMessageCode：认证错误代码authMessageDesc：认证错误描述3.3.2.2.2accessControlResult节点Permit/DenyaccessControlResult：网关根据规则对该用户计算的访问控制结果。“Permit”

17、表示允许访问。“Deny”表示禁止访问。当认证请求报文中节点值为“false”时，此节点在响应报文中不出现。3.3.2.2.3attributes节点 属性值attributes：用户属性列表attr：每个表示属性的定义name：所请求属性的名称，与请求报文中相同。namespace：所请求属性命名空间，与请求报文中相同。parentName：所请求属性的子属性的父级名称(或CODE)。当请求的属性有子属性时，将会返回该属性下所有相应属性。节点值：根据“name”和“namespace”取回的属性值(或CODE)，如：attr name= X509Certificate.SubjectDN n

18、amespace=CN=test,O=jit,C=cn。当存在多值的情况使用空格(“ ”)进行分隔，例如:123 456。3.4标准报文示例3.4.1认证原文产生服务请求报文示例 1.0 OriginalService testApp3.4.2认证原文产生服务响应报文示例1.0OriginalServicefalsekr5wEimbU83.4.3认证服务请求报文示例 1.0 AuthenService testApp MIIDiAYJKoZIhvcNAQcskBn0guQRgpOuU1c63QaB0= kr5wEimbU8 attr name=机构字典 namespace=” 3.4.4认证服务响应报文示例 1.0 AuthenServicefalse attr name=X509Certificate.SubjectDN namespace=”cn=test,o=jit,c=cnattr name=机构字典 namespace=”北京吉大正元attr name=部门 parentName=北京吉大正元 namespace=”