吉大正元身份认证网关报文认证应用接入培训教材V270816I22.docx
《吉大正元身份认证网关报文认证应用接入培训教材V270816I22.docx》由会员分享，可在线阅读，更多相关《吉大正元身份认证网关报文认证应用接入培训教材V270816I22.docx（19页珍藏版）》请在冰点文库上搜索。
吉大正元身份认证网关报文认证应用接入培训教材V270816I22
吉大正元身份认证CA
集中认证应用接入培训教材
Version2.7
中国·北京市海淀区知春路113号银网中心B座2层
电话：
86-010-62618866传真：
86-010-82610068
吉大正元信息技术股份有限公司
1引言
1.1服务概述
集中认证服务是吉大正元身份认证网关I（以下简称网关）面向各种应用系统提供的一种统一的、高强度的身份认证服务。
通过集中认证服务应用系统可以将用户的身份凭据（证书或用户名/口令）提交给网关，网关对用户的身份凭据进行认证，认证后将认证结果、用户的身份信息及用户的属性信息返回给应用系统。
集中认证服务保证了众多应用系统之间认证的权威性、安全性、用户身份的唯一性，避免了因在不同的应用系统中存在多重用户身份信息而难以管理的问题。
1.2适用网关版本
本文档所描述的集中认证应用接入改造方法适用于I2.2.2版本。
2认证原理
集中认证服务以基于X509证书的身份认证机制取代应用系统中原有的基于用户名/口令的传统身份认证机制。
集中认证服务实际上包含两个服务：
认证原文产生服务和认证服务，认证也分为两个过程：
请求认证原文和请求身份认证。
第一个过程是为了拿到网关提供的认证原文，当用户使用应用系统的客户端程序登录应用服务器时，首先由应用系统的客户端发起，应用客户端先向应用服务端请求认证原文（该认证原文用来生成后面认证服务要用到的认证请求包），应用服务端收到请求后发出请求向网关请求认证原文，网关收到请求后会产生认证原文并将原文返回给应用服务端，应用服务端再将原文返回给应用客户端，应用客户端拿认证原文第一个过程结束。
第二个过程是进行身份认证，应用客户端拿到原文后会弹出一个对话框让用户选择要用来进行身份认证的证书，用户指定证书后应用客户端使用认证原文和用户证书产生认证请求包发给应用服务端，应用服务端收到认证请求包后向网关发起身份认证请求，网关收到请求后根据认证请求包中的内容对用户身份进行认证，认证成功后网关会将认证结果和用户的属性信息返回给应用服务端，应用服务端根据这些信息可以对用户的登录请求做出回应。
如果网关对用户进行身份认证时失败，则会向应用服务端返回错误信息，应用服务端可以对这些错误信息加以处理，例如：
将信息返回给客户端显示，提示用户重新登录等。
3通信报文
集中认证服务支持明文、密文（SSL）两种通讯模式，承载协议采用http协议，业务通信报文采用XML格式，分为报文头和报文体两部分内容。
报文头存放通用信息，如服务类型、版本等信息；报文体存放业务数据。
3.1承载协议
集中认证服务采用标准的http协议作为通讯承载协议，下面示例中蓝色部分需要应用系统根据实际环境调整。
1.请求协议格式范例：
POSTuriHTTP/1.1
Accept-Language:
zh-cn
Content-Type:
text/plain
Accept-Encoding:
gzip,deflate
Host:
ip：
port
Content-Length:
发送数据长度
Connection:
Keep-Alive
Cache-Control:
no-cache
2.响应协议格式范例：
HTTP/1.1200OK
Server:
Apache-Coyote/1.1
Content-Type:
text/xml;charset=UTF-8
Content-Length:
回应数据长度
Date:
Wed,08Jul200902:
11:
07GMT
3.2认证原文产生服务报文
3.2.1请求报文说明
请求报文分为报文头和报文体，报文头由版本信息和服务类型两部分组成，报文体中是应用标识。
3.2.1.1报文头
1.0
OriginalService
✧version：
报文版本信息。
✧servicetype：
服务类型，网关会根据服务类型指定的服务将请求分发给该服务。
3.2.1.2报文体
testApp
✧appid：
应用系统在网关注册的应用标识，网关收到请求时会检查应用标识是否已经在网关注册，如果未注册则拒绝处理，返回错误信息。
3.2.2响应报文说明
响应报文分为报文头和报文体。
报文头由版本信息、服务类型、错误信息状态和错误信息四部分组成。
报文体中是认证原文。
3.2.2.1报文头
1.0
OriginalService
false
MESSAGE_CODE_13001001
报文解析异常
✧version：
报文版本信息。
✧servicetype：
服务类型，网关会根据服务类型指定的服务将请求分发给该服务。
✧messageState：
表示业务是否出现异常情况。
“true”表示出现了异常。
当值为“true”时，“messageCode”和“messageDesc”结点会给出错误代码及描述；“false”表示业务正常。
无“messageCode”和“messageDesc”结点。
✧messageCode：
错误代码
✧messageDesc：
错误描述
3.2.2.2报文体
kr5wEimbU8
✧original：
认证原文。
3.3认证服务报文
3.3.1请求报文说明
请求报文分为报文头和报文体。
报文头由版本信息和服务类型两部分组成。
报文体由应用信息、身份信息、访问控制请求状态、用户属性请求列表四部分组成。
3.3.1.1报文头
完整的请求报文头内容如下：
1.X
AuthenService
✧version：
报文版本信息。
标准的BS应用系统和已经具有会话管理的CS应用系统改造时，客户端到应用服务器申请原文，版本号为1.0；没有会话管理的CS应用系统和没有服务端的CD（客户端/数据库）应用系统改造时，客户端到网关申请原文，版本号为1.1。
✧servicetype：
服务类型，AuthenService，表示请求的是集中认证服务。
两个节点的内容在报文中固定不变。
3.3.1.2报文体
典型的请求报文体内容如下：
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节点
testApp
✧appId：
应用系统在网关注册的应用标识，网关收到请求时会检查应用标识是否已经在网关注册，如果未注册则拒绝处理，返回错误信息。
3.3.1.2.3authen节点
XXXXXXX
XXXXXXX
admin
password
✧authen：
身份信息结点，此节点表示用户的各种身份凭据信息。
✧authCredential：
认证凭据，可以多次出现，表示用户的一种身份信息，例如：
证书、用户名/口令等。
✧authMode：
认证方式，表示authCredential节点的信息需要何种认证方式进行处理，目前支持两种认证方式，即：
“cert”和“password”，分别表示证书认证方式和口令认证方式。
✧detach：
认证请求包，Detach格式的认证请求包中不包含认证原文，所以需要与节点配合使用将认证原文提交给网关。
✧original：
网关颁发的认证原文，原文在提交认证时需经过Base64编码。
✧certInfo：
X509证书，证书在提交认证时需经过Base64编码。
✧attach：
网关支持的另一种格式的认证请求包，这种格式的请求包中会包含认证原文，所以不需要像使用节点一样单独提交原文。
在同一节点下结点不能与和结点同时使用。
✧username：
用户名。
✧password：
密码。
3.3.1.2.4accessControl节点
true
✧accessControl：
是否检查访问控制状态。
false表示不检查，当设置为“false”时，网关不做任何处理，响应报文中也不会有任何相关信息。
true表示检查，当设置为“true”时，网关检查用户是否允许访问此应用，并在报文中给出相应的信息。
3.3.1.2.5attributes节点
该节点表示应用系统需要请求的用户属性这些属性来自于用户的身份证书、UMS和PMS，在实际应用环境中应用系统可根据需要向网关请求用户的所有属性、指定属性或不请求属性。
✧attributes：
用户属性请求列表
✧attributeType：
用户属性请求类型。
分为“all”、“portion”、“none”。
“all”表示请求所有属性信息；“portion”表示只请求节点列表中指定的属性信息；“none”表示不请求任何属性信息。
✧attr：
指定要请求的某项用户属性信息，例如：
X509Certificate.SubjectDN表示请求的是用户身份证书中的主题（证书DN）信息。
✧name：
所请求属性的名称，可为中文。
常用取值如下：
证书认证时使用
X509Certificate.NotBefore证书开始生效时间
X509Certificate.NotAfter证书结束生效时间
X509Certificate.SubjectDN证书主题
X509Certificate.SerialNumber证书序列号
X509Certificate.IssuerDN证书颁发者DN
口令认证时使用
UMS.UserID用户ID
UMS.Username用户名
UMS.LogonName用户登录名
由于有部分信息是自定义属性，属性名称不确定，依实际情况而定。
因此建议在调试时先将“attributeType”的值设置为“all”，当调试通过后，再将“attributeType”改为“portion”。
✧namespace：
所请求属性的命名空间。
常用取值如下（常量值，无具体含义）：
证书属性命名空间：
UMS3.X属性命名空间：
其它版本UMS属性命名空间：
3.3.2响应报文说明
响应报文分为报文头和报文体。
报文头由版本信息、服务类型、错误信息状态和错误信息四部分组成。
报文体由认证结果、访问控制结果和用户属性列表三部分组成。
3.3.2.1报文头
完整的响应报文头内容如下：
1.X
AuthenService
false/true
00000001
报文解析异常
✧version：
报文版本信息。
✧servicetype：
服务类型，网关会根据服务类型指定的服务将请求分发给该服务。
✧messageState：
表示业务是否出现异常情况。
“true”表示出现了异常。
当值为“true”时，“messageCode”和“messageDesc”结点会给出错误代码及描述；“false”表示业务正常。
无“messageCode”和“messageDesc”结点。
✧messageCode：
错误代码
✧messageDesc：
错误描述
3.3.2.2报文体
常用的响应报文体内容如下：
Permit/Deny
属性值
属性值
3.3.2.2.1authResultSet节点
00000001
证书被吊销
✧authResultSet：
认证结果集
✧allFailed：
是否所有认证请求都失败。
“true”所有认证请求都失败；“false”至少有一种认证请求成功。
✧authResult：
认证结果项
✧authMode：
认证的方式。
包括“cert”和“password”，各表示证书认证方式和口令认证方式。
✧success：
认证结果。
“true”表示当前认证方式成功。
“false”表示认证失败，并出现下面两个结点。
做错误提示。
✧authMessageCode：
认证错误代码
✧authMessageDesc：
认证错误描述
3.3.2.2.2accessControlResult节点
Permit/Deny
✧accessControlResult：
网关根据规则对该用户计算的访问控制结果。
“Permit”表示允许访问。
“Deny”表示禁止访问。
当认证请求报文中节点值为“false”时，此节点在响应报文中不出现。
3.3.2.2.3attributes节点
namespace="X.509">属性值
✧attributes：
用户属性列表
✧attr：
每个表示属性的定义
✧name：
所请求属性的名称，与请求报文中相同。
✧namespace：
所请求属性命名空间，与请求报文中相同。
✧parentName：
所请求属性的子属性的父级名称（或CODE）。
当请求的属性有子属性时，将会返回该属性下所有相应属性。
✧节点值：
根据“name”和“namespace”取回的属性值（或CODE），如：
CN=test,O=jit,C=cn
。
当存在多值的情况使用空格（“”）进行分隔，例如:
123456。
3.4标准报文示例
3.4.1认证原文产生服务请求报文示例
xmlversion="1.0"encoding="UTF-8"?
>
1.0
OriginalService
testApp
3.4.2认证原文产生服务响应报文示例
xmlversion="1.0"encoding="UTF-8"?
>
1.0
OriginalService
false
kr5wEimbU8
3.4.3认证服务请求报文示例
xmlversion="1.0"encoding="UTF-8"?
>
1.0
AuthenService
testApp
MIIDiAYJKoZIhvcNAQc……skBn0guQRgpOuU1c63QaB0=
kr5wEimbU8
namespace=">
namespace=”
3.4.4认证服务响应报文示例
xmlversion="1.0"encoding="UTF-8"?
>
1.0
AuthenService
false
namespace=”
cn=test,o=jit,c=cn
namespace=”
北京吉大正元
namespace=”
升级会员 