webservice开发技术说明书.docx

webservice开发技术说明书.docx

《webservice开发技术说明书.docx》由会员分享，可在线阅读，更多相关《webservice开发技术说明书.docx（17页珍藏版）》请在冰豆网上搜索。

webservice开发技术说明书

1前言

在NC环境中发布WS服务以及创建SEI（serviceendpointinterface）最便捷的方式就是使用NCEclipse插件的相关功能。

使用前需要手动安装NCWebServiceEclipse插件：

nc.uap.mde.wstools_1.0.0.jar。

以下描述的发布过程假设该插件已成功安装且java工程为NCModuleProject工程。

2发布服务

在NC中发布WS服务可简单描述如下：

⏹由Java接口创建WSDL文件。

⏹如果Java接口中引用了自定义的Java类，需要创建相应的XSD文件。

⏹在模块下的UPM文件中配置WS服务。

⏹如果需要WS安全方面的考虑还需要配置ws-security.xml文件，及相关的证书管理配置。

注意：

使用NC的Eclipse插件配置UPM文件的过程中，可以自动创建WSDL文件和XSD文件。

这样比单独创建WSDL/XSD文件便捷。

2.1创建WSDL文件

⏹在EclipseIDE中选中要发布为WS服务的接口文件，点击右键弹出功能菜单。

选择WSTools下的GenarateWSDL菜单项，如图：

⏹选择后弹出WSDL创建面板，设置WSDL文件的保存路径。

Ø勾选Cascade复选框：

表示如果该接口引用到了其它的自定义Java类，则一并生成相应的XSD文件。

Ø勾选force复选框：

表示如果该路径下已存在同名的WSDL文件，则覆盖。

如图：

⏹点击“Finish”按钮完成WSDL文件的创建工作。

2.2创建XSD文件

关联类的XSD文件即可以在1.1创建WSDL文件的过程中级联创建，也可以单独创建。

过程如下：

⏹在EclipseIDE中选中准备创建XSD的Java类文件，点击右键弹出功能菜单。

选择WSTools下的GenarateXSD菜单项，如图：

⏹选择后弹出XSD创建面板，设置XSD文件的保存路径。

Ø勾选Cascade复选框：

表示如果该类引用到了其它的自定义Java类，则一并生成相应的XSD文件。

Ø勾选force复选框：

表示如果该路径下已存在同名的XSD文件，则覆盖。

如图：

⏹点击“Finish”按钮完成XSD文件的创建工作。

2.3配置UPM文件

配置UPM文件的工作量并不大，可手工也可使用NC工具。

下面对使用NC工具配置的流程加以描述，其中涉及到NCWebServiceSecurity方面的规范知识可参考《WebService安全配置》文档。

⏹在EclipseIDE中选中要发布为WS服务的接口文件或实现类，点击右键弹出功能菜单。

选择WSTools下的PublishWebService菜单项后弹出UPM文件选择窗口，如图：

⏹点击“Next”后进入如下配置页，最下面的interface，impl是两个必填项。

指明要发布为ws服务的接口和实现类。

“设置属性”栏中的各项属性是NC组件正常发布所需要的配置项，这里不做介绍，可参考组件发布的相关文档。

需要指出的是如果配置了组件名则这个组件名就是WS的服务名，否则系统会将下页配置的Address做为WS的服务名。

⏹点击“Next”后进入如下配置页。

ExtensionClass：

指定了Server启动时部署这个组件的处理类。

WebServiceStyle：

暂时只能选NCspecify。

如果勾选了“CreateWSDLifnotexist”项，则当未创建wsdl、xsd文件时会自动创建。

Wsdllocation：

指出wsdl文件的位置。

Address：

是WS服务地址，结构为“/”+服务名。

Interceptor：

拦截器。

⏹点击“Next”进入WebService安全配置项。

勾选webservice安全配置项。

选择KeyStore，从modules/uapws/config/ws-security.xml中选择。

默认的是该文件中cryptoid为default的KeyStore。

decKS：

解密需要的KeyStore。

encKS：

加密需要的KeyStore。

signKS：

签名需要的KeyStore。

verifyKS：

验证签名需要的KeyStore。

⏹点击“Next”，进入WebService安全详细信息配置页。

Ø配置Protect项。

如果在上一页的安全配置项中勾选了“要求认证授权”，则在当前的详细信息配置页中需要配置Protect项。

如图：

认证组件：

如果没有配置，表示使用系统默认的认证器。

他为对nc.uap.ws.security.IAuthenticator组件的引用。

默认为名称为nc.uap.ws.security.IAuthenticator的组件。

授权组件：

如果没有配置，表示使用系统默认的权限机制，他为对nc.uap.ws.security.IAccessController的组件的引用，默认为名称nc.uap.ws.security.IAccessController的组件。

Ø配置UserToken项。

如果在上一页的安全配置项中勾选了“要求输出token”，则在当前的详细信息配置页中需要配置UserToken项。

如图：

在profile下拉框中点选“UsernameProfile”后出现如下配置页。

配置在信息输出时提供给别人的主体信息，profile表示遵循的SecurityToken规范，目前只支持UsernameProfile。

对于UsernameToken的profile，有属性：

user,password,cbClass,cbRef。

如果指定了user/password就不需要cbClass,cbRef的配置。

user/password表示一种静态的用户名/密码信息提供，而cbClass,cbRef表示一种动态的复杂的用户名密码提供方式。

cbClass为javax.security.auth.callback.CallbackHandler的类，cbRef为javax.security.auth.callback.CallbackHandler组件的引用（该描述适合后续的sign,encrypt的描述。

Ø配置Signature项。

如果在上一页的安全配置项中勾选了“要求输出签名”，则在当前的详细信息配置页中需要配置Signature项。

如图：

签名确认：

勾选此项表示在应答时需要返回请求方的signature，否则不返回请求方的signature。

签名用户：

从签名对应的KeyStore中选取用于签名的私钥名。

Callback：

如果签名用户的获取方式比较复杂不能直接指定而是通过callback方式获取的。

则此处需要配置callback项。

Key标识方式：

指示签名或加密的key的值应用方式，默认为IssuerSerial。

Canonical：

指示正规化算法没有设定，默认为，http:

//www.w3.org/2001/10/xml-exc-c14n#。

算法：

指定Key的算法。

可以不选，此时系统会自动判断算法类型。

签名元素：

指定需要签名的信息。

Ø配置verify项。

如果在上一页的安全配置项中勾选了“要求输入签名”，则在当前的详细信息配置页中需要配置Verify项。

如图：

如果不存在通信双方互为Server的情况（NC的目前应用基本不存在），建议不要勾选Confirm项。

Ø配置encrypt项。

如果在上一页的安全配置项中勾选了“要求输出加密”，则在当前的详细信息配置页中需要配置encrypt项。

如图：

Ø

加密用户：

从加密对应的KeyStore中选取用于加密的密钥名。

用户回调类：

如果加密用户的获取方式比较复杂不能直接指定而是通过callback方式获取的。

则此处需要配置用户回调类。

Key标识方式：

指示签名或加密的key的值应用方式，默认为IssuerSerial。

Key加密算法：

系统只支持RSA15算法。

算法：

加密算法。

加密元素：

指定需要加密的信息。

Ø配置decrypt项。

目前没有需要配置的内容。

完成上面的配置后，点击“Finish”按钮，保存配置信息。

3客户端调用

NC的WebService客户端调用需要有服务接口类，可以利用WSDL文件创建服务接口，WSDL文件可以远程获取。

拥有了服务接口后就可以利用API进行客户端对服务端的访问了。

3.1创建服务接口

注意：

使用NC的Eclipse插件创建JAVA接口的过程中，可以自动创建相关JAVA类文件。

这样比单独创建相关JAVA类文件便捷。

3.1.1创建相关JAVA类文件

⏹在EclipseIDE中选中要创建JAVA类文件的XSD文件，点击右键弹出功能菜单。

选择WSTools下的GenarateJavaClass菜单项，如图：

⏹选择后弹出Java类文件创建面板，设置类文件的保存路径。

如图：

force复选框表示是否要覆盖该保存路径下的同名文件。

点击“Finish”按钮完成创建工作。

3.1.2创建JAVA接口

⏹在EclipseIDE中选中要创建SEI的WSDL文件，点击右键弹出功能菜单。

选择WSTools下的GenarateJavaInterface菜单项，如图：

⏹选择后弹出SEI创建面板，设置SEI文件的保存路径。

如图：

cascade复选框：

表示是否级联创建相关的Java类文件。

force复选框：

表示是否要覆盖该保存路径下的同名文件。

点击“Finish”按钮完成创建工作。

3.2API使用

可以通过API进行安全特性的配置和控制:

3.2.1WSS4JConfig

配置的核心类，所有安全属性的配置信息都在里面。

每个属性都有get/set方法。

现逐一介绍其属性的含义。

ØencCryptoId：

在NC的WebService安全配置文件中，Crypto标签描述了KeyStore的访问信息。

CryptoId是Crypto的唯一标识。

encCryptoId标识的Crypto描述了用于加密信息所使用的Key的访问信息。

ØdecCryptoId：

用于解密的Crypto。

ØsignCryptoId：

用于签名的Crypto。

ØverifyCryptoId：

用于验证签名的Crypto。

ØsecurityToken：

安全令牌，类型是SecurityToken，NC目前只支持UsernameToken。

Øsign:

类型是SignAdvice，描述了签名信息。

Øverify：

类型是VerifyAdvice，描述了验证签名的信息。

Øencrypt：

类型是EnryptAdvice，描述了加密的信息。

Ødecrypt：

类型是DecryptAdvice，描述了解密的信息。

Øauthentication：

类型是Authentication，描述了认证信息。

3.2.2UsernameToken

用于配置进行请求的主体，其属性描述如下：

Øuser：

用户名。

Øpassword：

密码。

Ønonce：

布尔型，是否附带随机数。

Øcreated：

布尔型，是否附带Token创建时间。

ØcallbackHandler：

类型是CallbackHandler，获取密码的回调处理类。

ØpwType：

类型是PwType，密码的类型，包括三种：

✓PasswordNone：

没有密码。

✓PasswordText：

密码是明文形式。

✓PasswordDigest：

密码是摘要形式。

3.2.3Cryptic

该类是SignAdvice、EncryptAdvice的超类。

其属性描述如下：

Øuser：

用户名，用来进行私钥签名的key的标识。

Øalgorithm：

加密算法。

ØcallbackHandler：

类型是CallbackHandler，用来获取密码的回调处理类。

ØkeyIdentifier：

类型是KeyIdentifier，指明Key的获取方式。

Øparts：

类型是List加密的部分。

3.2.4SignAdvice

用于保存签名信息，继承了Cryptic，其属性描述如下：

Øconfirm：

布尔型。

应答时，是否需要返回请求方的signature。

这个属性适合在服务方配置。

ØcanonicalAlgorithm：

规范算法。

3.2.5EncryptAdvice

用于保存加密信息，继承了Cryptic，其属性描述如下：

ØkeyEncryptionAlgorithm：

Key加密算法类型。

3.2.6DecryptAdvice

用于保存解密信息。

暂无任何属性。

3.2.7VerifyAdvice

用于保存校验信息，其属性描述如下：

Øconfirm：

布尔类型。

是否需要验证服务方的应答信息中是否包含自己发送请求的signature。

这个属性只适合用在请求方配置。

3.2.8测试用例

publicclassEmployeeServiceClientextendsAbstractWSTestCase{

protectedStringgetPort（）{

return"8080";

}

protectedStringgetSecurityConfig（）{

return"nc/uap/ws/test/ws-security.xml";

}

//只认证

publicvoidtestInsertUT（）{

EmployeeServiceclient=getLocator（）.lookup（EmployeeService.class）;

Departmentdept=newDepartment（）;

Employeee1=newEmployee（）;

e1.setName（"hgy"）;

e1.setAge（30）;

Employeee2=newEmployee（）;

e2.setName（"hgn"）;

e2.setAge（20）;

Mapf=newHashMap（）;

f.put（"aaa","f-aaa"）;

f.put（"bbb","f-bbb"）;

dept.setFeature（f）;

//设置用户名密码

WSS4JConfigwss4jContext=newWSS4JConfig（）;

wss4jContext.setSecurityToken（newUsernameToken（"admin","uapws"））;

（（Client）client）.setWSS4JConfig（wss4jContext）;

Departmentobj=client.insert（newEmployee[]{e1,e2},dept）;

assertTrue（obj.getEmployees（）.length==2）;

assertTrue（obj.getEmployees（）[0].getName（）.equals（"hgy"））;

assertTrue（obj.getEmployees（）[0].getAge（）==30）;

assertTrue（obj.getFeature（）.size（）==2）;

assertTrue（obj.getFeature（）.get（"aaa"）.equals（"f-aaa"））;

}

//进行签名的安全示例

publicvoidtestInsertSign（）{

WSS4JConfigwss4jContext=newWSS4JConfig（）;

wss4jContext.setSecurityToken（newUsernameToken（"admin","uapws"））;

//默认采用了UsernameToke中的用户名密码信息访问私钥签名

wss4jContext.setSignAdvice（newSignAdvice（））;

（（Client）client）.setWSS4JConfig（wss4jContext）;…

}

//加密

publicvoidtestInsertEnc（）{…

//设置用于加密的信息

WSS4JConfigwss4jContext=newWSS4JConfig（）;

wss4jContext.setSecurityToken（newUsernameToken（"admin","uapws"））;

wss4jContext.setEncryptAdvice（newEncryptAdvice（"uapws"））;

（（Client）client）.setWSS4JConfig（wss4jContext）;…

}

//同事签名加密

publicvoidtestInsertSignEnc（）{…

WSS4JConfigwss4jContext=newWSS4JConfig（）;

wss4jContext.setSecurityToken（newUsernameToken（"admin","uapws"））;

wss4jContext.setSignAdvice（newSignAdvice（））;

wss4jContext.setEncryptAdvice（newEncryptAdvice（"uapws"））;…

}

}

而后台服务会根据配置，自适应的签名/加密或者强制加密签名。