吉大正元身份认证网关报文认证应用接入培训教材_V2.7_20100816_I2.2..doc

吉大正元身份认证吉大正元身份认证 CA 集中认证应用接入培训教材集中认证应用接入培训教材 Version 2.7 中国北京市海淀区知春路 113 号银网中心 B 座 2 层 电话：86传真：86吉大正元信息技术股份有限公司吉大正元信息技术股份有限公司 XX 产品安装手册 目录目录 1引言引言.1 1.1服务概述.1 1.2适用网关版本.1 2认证原理认证原理1 3通信报文通信报文2 3.1承载协议.2 3.2认证原文产生服务报文.2 3.2.1请求报文说明.2 3.2.2响应报文说明.2 3.3认证服务报文.3 3.3.1请求报文说明.3 3.3.2响应报文说明.5 3.4标准报文示例.7 3.4.1认证原文产生服务请求报文示例.7 3.4.2认证原文产生服务响应报文示例.7 3.4.3认证服务请求报文示例.7 3.4.4认证服务响应报文示例.8 4应用改造流程应用改造流程9 4.1第一步：客户端请求认证原文.9 4.2第二步：服务端请求认证原文.9 4.3第三步：网关返回认证原文.10 4.4第四步：服务端返回认证原文.10 4.5第五步：客户端认证.10 4.6第六步：应用服务端认证.10 4.7第七步：网关返回认证响应.10 4.8第八步：服务端处理.10 XX 产品安装手册 1引言引言 1.1 服务概述服务概述 集中认证服务是吉大正元身份认证网关 I（以下简称网关）面向各种应用系统提供的一种统一的、高强度的 身份认证服务。通过集中认证服务应用系统可以将用户的身份凭据（证书或用户名/口令）提交给网关，网关对 用户的身份凭据进行认证，认证后将认证结果、用户的身份信息及用户的属性信息返回给应用系统。集中认证 服务保证了众多应用系统之间认证的权威性、安全性、用户身份的唯一性，避免了因在不同的应用系统中存在 多重用户身份信息而难以管理的问题。 1.2 适用网关版本适用网关版本 本文档所描述的集中认证应用接入改造方法适用于 I2.2.2 版本。 2认证原理认证原理 集中认证服务以基于 X509 证书的身份认证机制取代应用系统中原有的基于用户名/口令的传统身份认证机 制。集中认证服务实际上包含两个服务：认证原文产生服务和认证服务，认证也分为两个过程：请求认证原文 和请求身份认证。 应应用用系系统统网网关关 请求认证原文 请求身份认证 第一个过程是为了拿到网关提供的认证原文，当用户使用应用系统的客户端程序登录应用服务器时，首先 由应用系统的客户端发起，应用客户端先向应用服务端请求认证原文（该认证原文用来生成后面认证服务要用 到的认证请求包） ，应用服务端收到请求后发出请求向网关请求认证原文，网关收到请求后会产生认证原文并将 原文返回给应用服务端，应用服务端再将原文返回给应用客户端，应用客户端拿认证原文第一个过程结束。 应应用用系系统统 客客户户端端 应应用用系系统统 服服务务端端 网网关关 请求认证原文请求认证原文 第二个过程是进行身份认证，应用客户端拿到原文后会弹出一个对话框让用户选择要用来进行身份认证的 证书，用户指定证书后应用客户端使用认证原文和用户证书产生认证请求包发给应用服务端，应用服务端收到 认证请求包后向网关发起身份认证请求，网关收到请求后根据认证请求包中的内容对用户身份进行认证，认证 成功后网关会将认证结果和用户的属性信息返回给应用服务端，应用服务端根据这些信息可以对用户的登录请 求做出回应。如果网关对用户进行身份认证时失败，则会向应用服务端返回错误信息，应用服务端可以对这些 错误信息加以处理，例如：将信息返回给客户端显示，提示用户重新登录等。 应应用用系系统统 客客户户端端 应应用用系系统统 服服务务端端 网网关关 认证请求包请求身份认证 XX 产品安装手册 3通信报文通信报文 集中认证服务支持明文、密文（SSL）两种通讯模式，承载协议采用 http 协议，业务通信报文采用 XML 格 式，分为报文头和报文体两部分内容。报文头存放通用信息，如服务类型、版本等信息；报文体存放业务数据。 3.1 承载协议承载协议 集中认证服务采用标准的 http 协议作为通讯承载协议，下面示例中蓝色部分需要应用系统根据实际环境调 整。 1.请求协议格式范例： POST uri HTTP/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.1 200 OK Server: Apache-Coyote/1.1 Content-Type: text/xml;charset=UTF-8 Content-Length: 回应数据长度 Date: Wed, 08 Jul 2009 02:11:07 GMT 3.2 认证原文产生服务报文认证原文产生服务报文 .1 请求报文说明请求报文说明 请求报文分为报文头和报文体，报文头由版本信息和服务类型两部分组成，报文体中是应用标识。 报文头报文头 1.0 OriginalService version：报文版本信息。 servicetype：服务类型，网关会根据服务类型指定的服务将请求分发给该服务。 报文体报文体 testApp appid：应用系统在网关注册的应用标识，网关收到请求时会检查应用标识是否已经在网关注册，如果 未注册则拒绝处理，返回错误信息。 .2 响应报文说明响应报文说明 响应报文分为报文头和报文体。报文头由版本信息、服务类型、错误信息状态和错误信息四部分组成。报 文体中是认证原文。 XX 产品安装手册 报文头报文头 1.0 OriginalService false MESSAGE_CODE_13001001 报文解析异常报文解析异常 version：报文版本信息。 servicetype：服务类型，网关会根据服务类型指定的服务将请求分发给该服务。 messageState：表示业务是否出现异常情况。 “true”表示出现了异常。当值为“true”时， “messageCode”和“messageDesc”结点会给出错误代码及描述；“false”表示业务正常。无 “messageCode”和“messageDesc”结点。 messageCode：错误代码 messageDesc：错误描述 报文体报文体 kr5wEimbU8 original：认证原文。 3.3 认证服务报文认证服务报文 .1 请求报文说明请求报文说明 请求报文分为报文头和报文体。报文头由版本信息和服务类型两部分组成。报文体由应用信息、身份信息、 访问控制请求状态、用户属性请求列表四部分组成。 报文头报文头 完整的请求报文头内容如下： 1.X AuthenService version：报文版本信息。标准的 BS 应用系统和已经具有会话管理的 CS 应用系统改造时，客户端到应 用服务器申请原文，版本号为 1.0；没有会话管理的 CS 应用系统和没有服务端的 CD（客户端/数据库） 应用系统改造时，客户端到网关申请原文，版本号为 1.1。 servicetype：服务类型，AuthenService，表示请求的是集中认证服务。 两个节点的内容在报文中固定不变。 报文体报文体 典型的请求报文体内容如下： xxx.xxx.xxx.xxx testApp XX 产品安装手册 XXXXXXX XXXXXXX admin password true .1clientInfo 节点 xxx.xxx.xxx.xxx clientInfo：客户端信息结点，该节点下可以添加任意的客户端信息。 clientIP：客户端 IP 地址。 .2appId 节点 testApp appId：应用系统在网关注册的应用标识，网关收到请求时会检查应用标识是否已经在网关注册，如果 未注册则拒绝处理，返回错误信息。 .3authen 节点 XXXXXXX XXXXXXX admin password authen：身份信息结点，此节点表示用户的各种身份凭据信息。 authCredential：认证凭据，可以多次出现，表示用户的一种身份信息，例如：证书、用户名/口令等。 authMode：认证方式，表示 authCredential 节点的信息需要何种认证方式进行处理，目前支持两种认 证方式，即：“cert”和“password” ，分别表示证书认证方式和口令认证方式。 detach：认证请求包，Detach 格式的认证请求包中不包含认证原文，所以需要与节点配合使 用将认证原文提交给网关。 original：网关颁发的认证原文，原文在提交认证时需经过 Base64 编码。 certInfo：X509 证书，证书在提交认证时需经过 Base64 编码。 attach： 网关支持的另一种格式的认证请求包，这种格式的请求包中会包含认证原文，所以不需要像 使用节点节点一样单独提交原文。在同一节点下结点不能与和 结点同时使用。 username：用户名。 password：密码。 XX 产品安装手册 .4accessControl 节点 true accessControl：是否检查访问控制状态。false 表示不检查，当设置为“false”时，网关不做任何处理， 响应报文中也不会有任何相关信息。true 表示检查，当设置为“true”时，网关检查用户是否允许访 问此应用，并在报文中给出相应的信息。 .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证书颁发者证书颁发者 DNDN 口令认证时使用口令认证时使用 UMS.UserID用户用户 IDID UMS.Username用户名用户名 UMS.LogonName用户登录名用户登录名 由于有部分信息是自定义属性，属性名称不确定，依实际情况而定。因此建议在调试时先将 “attributeType”的值设置为“all” ，当调试通过后，再将“attributeType”改为“portion” 。 namespace：所请求属性的命名空间。常用取值如下（常量值，无具体含义）： 证书属性命名空间证书属性命名空间：/cinas/ias/ns/saml/saml11/X.509 UMS3.XUMS3.X 属性命名空间属性命名空间：/ums/ns/3.0/user 其它版本其它版本 UMSUMS 属性命名空间属性命名空间：/ums/ns/user .2 响应报文说明响应报文说明 响应报文分为报文头和报文体。报文头由版本信息、服务类型、错误信息状态和错误信息四部分组成。报 文体由认证结果、访问控制结果和用户属性列表三部分组成。 报文头报文头 完整的响应报文头内容如下： 1.X AuthenService false/true 00000001 报文解析异常报文解析异常 version：报文版本信息。 XX 产品安装手册 servicetype：服务类型，网关会根据服务类型指定的服务将请求分发给该服务。 messageState：表示业务是否出现异常情况。 “true”表示出现了异常。当值为“true”时， “messageCode”和“messageDesc”结点会给出错误代码及描述；“false”表示业务正常。无 “messageCode”和“messageDesc”结点。 messageCode：错误代码 messageDesc：错误描述 报文体报文体 常用的响应报文体内容如下： Permit/Deny 属性值属性值 属性值属性值 .1authResultSet 节点 00000001 证书被吊销证书被吊销 authResultSet：认证结果集 allFailed：是否所有认证请求都失败。 “true”所有认证请求都失败；“false”至少有一种认证请求成功。 authResult：认证结果项 authMode：认证的方式。包括“cert”和“password” ，各表示证书认证方式和口令认证方式。 success：认证结果。 “true”表示当前认证方式成功。 “false”表示认证失败，并出现下面两个结点。 做错误提示。 authMessageCode：认证错误代码 authMessageDesc：认证错误描述 .2accessControlResult 节点 Permit/Deny accessControlResult：网关根据规则对该用户计算的访问控制结果。 “Permit”表示允许访问。 “Deny” 表示禁止访问。当认证请求报文中节点值为“false”时，此节点在响应报文中不出现。 .3attributes 节点 XX 产品安装手册 属性值属性值 attributes：用户属性列表 attr：每个表示属性的定义 name：所请求属性的名称，与请求报文中相同。 namespace：所请求属性命名空间，与请求报文中相同。 parentName：所请求属性的子属性的父级名称(或 CODE)。当请求的属性有子属性时，将会返回该属性 下所有相应属性。 节点值：节点值：根据“name”和“namespace”取回的属性值(或 CODE)，如： CN=test,O=jit,C=cn 。 当存在多值的情况使用空格(“ ”)进行分隔，例如:123 456。 3.4 标准报文示例标准报文示例 .1 认证原文产生服务请求报文示例认证原文产生服务请求报文示例 1.0 OriginalService testApp .2 认证原文产生服务响应报文示例认证原文产生服务响应报文示例 1.0 OriginalService false kr5wEimbU8 .3 认证服务请求报文示例认证服务请求报文示例 1.0 AuthenService XX 产品安装手册 testApp MIIDiAYJKoZIhvcNAQcskBn0guQRgpOuU1c63QaB0= kr5wEimbU8 .4 认证服务响应报文示例认证服务响应报文示例 1.0 AuthenService false cn=test,o=jit,c=cn 北京吉大正元北京吉大正元 产品部产品部 XX 产品安装手册 4应用改造流程应用改造流程 C/S 应用改造流程应用改造流程 应用系统在进行集中认证接入改造时需要将其原有的认证流程改造成网关集中认证业务流程，改造过程通 常需要 8 个步骤。改造流程示意图如下： 应用服务器 应用客户端 I网关 4、返回认证原文 1、请求认证原文 5、选择证书、产生认证请求包 7、返回认证响应 6、提交认证请求 8、根据认证响应 处理应用自身业务 3、返回认证原文 2、请求认证原文 1、 客户端请求认证原文客户端请求认证原文：应用客户端向应用服务端请求认证原文。 2、 服务端请求认证原文：服务端请求认证原文：应用服务端向网关请求认证原文。 3、 网关返回认证原文：网关返回认证原文：网关产生认证原文并返回给应用服务端。 4、 服务端返回认证原文：服务端返回认证原文：应用服务端将认证原文返回给应用客户端。 5、 客户端认证：客户端认证：应用客户端让用户选择证书，然后产生认证请求包并发给应用服务端发起认证请求。 6、 应用服务端认证：应用服务端认证：应用服务端将请求包发给网关请求身份认证。 7、 网关返回认证响应：网关返回认证响应：网关完成认证请求的处理后，将认证响应返回给应用服务端。 8、 服务端处理：服务端处理：应用服务端根据认证响应中的认证结果、用户属性等内容进行业务处理然后向客户端返 回响应。 4.1 第一步：客户端请求认证原文第一步：客户端请求认证原文 应用系统的客户端需要改造原先的认证、登录逻辑，首先要向服务端发起请求，请求认证原文。该原文是 用来产生认证请求包的，由网关产生并提供。此时应用系统的客户端与服务端之间的通讯方式和报文等均可依 据应用系统原有的机制进行设计实现。 4.2 第二步：服务端请求认证原文第二步：服务端请求认证原文 服务端需要改造原先的对客户端的认证、登录请求处理逻辑。此处分两种情况，第一种对于标准的 BS 应用 系统和已经具有会话管理的 CS 应用系统，可以在服务端产生认证原文（认证原文可以是一段随机字符序列或以 其它方式生成的字符序列） ，不用进行第二、三步改造，第二种对于没有会话管理的 CS 应用系统和没有服务端 的 CD（客户端/数据库）应用系统在接到客户端的请求后，需要将自己的应用标识（应用标识是应用系统在网 关注册的唯一标识）封装在认证原文产生服务的请求报文中，然后将请求提交给网关请求认证原文。认证原文 产生服务的请求报文请参照 3.4.1 认证原文产生服务请求报文示例，详细说明请参照：3.2.1 认证原文产生服务 请求报文说明，在各种语言平台下的报文封装方法请参考各平台 Demo 示例代码。 XX 产品安装手册 4.3 第三步：网关