正如 “Metro 简介” 所述,JAXB 2.x 数据绑定的参考实现和 JAX-WS 2.x 网络服务规范是 Metro 网络服务框架的核心。但是 JAXB 与 JAX-WS 本身只提供基本的网络服务支持,JAX-WS 并不包括 WS-* 技术,不能升级 SOAP 以便在企业级应用环境中工作,所以需要一些其他的软件组件来支持 WS-* 技术。
在 Metro 中,添加的主要组件是 Web 服务互操作性技术(Web Services Interoperability Technologies,WSIT)。WSIT 是原来称为 Project Tango 的当前版本,Project Tango 是 Sun 公司为 实现某些 WS-* 特性(包括安全可靠的消息传递)与 Microsoft .NET 平台之间的互操作性而付出的努力 。WSIT 向 Metro 提供 WS-SecurityPolicy、WS-Trust、WS-SecureConversation、WS- ReliableMessaging 等服务规范支持。而 WS-Security 的实际运行时处理由另外一个添加的组件 —— XML and WebServices Security Project (XWSS) 来实现。
本文展示如何通过 Metro 来使用和配置 WS-Security,将其作为一个独立的 Web 应用程序在 Glassfish 服务器外部使用。参见 下载 部分获取本文中的全部示例的完整源代码,该代码实现了此前在 本系列中使用的简单图书馆管理服务。
WSIT 基础
WSIT 负责配置 Metro 运行时以匹配一个服务的 WS-Policy 规范,包括诸如 WS-SecurityPolicy 之 类的 WS-Policy 扩展。除标准的 WS-Policy 扩展外,Metro 还使用策略文档中的自定义扩展来配置实现 安全处理所需的用户信息(如密匙存储位置和密码)。
WSIT 从 Web Services Description Language (WSDL) 服务描述中获取策略信息。在客户端,这可能 难以理解一些,因为用于 WSIT 配置的 WSDL 与用于定义 JAX-WS 服务的 WSDL 是分开的。如 “Metro 简介” 所述,用于配置 JAX-WS 客户端的 WSDL 可以直接从服务获取,也可以从生成 JAX-WS 代码之时 指定的位置获取。WSIT 使用的 WSDL 有一个固定的文件名(虽然这个文件能够使用一个 标记来引用一个带有完整 WSDL 的独立文件),并且总是通过类路径访问。
在服务器端,WSIT 要求在 WEB-INF/sun-jaxws.xml 配置文件(在 “Metro 简介” 中介绍过)中指 定的位置提供 WSDL。所提供的 WSDL 必须包含用于为 WSIT 配置用户信息的自定义扩展,但是这些自定 义扩展在为响应对服务端点的 HTT PGET 请求而提供的 WSDL 版本中被删除掉了。
这些用于配置 WSIT 用户信息的自定义扩展在服务器端和客户端看起来一样,但是在用于扩展元素的 XML 名称空间中不同。在客户端,名称空间是 http://schemas.sun.com/2006/03/wss/client;在服务器 端,名称空间是 http://schemas.sun.com/2006/03/wss/server。
Metro 中的 UsernameToken
“Axis2 WS-Security 基础” 使用了一个简单的 UsernameToken 例子来介绍 Axis2/Rampart 环境下 的 WS-Security。UsernameToken 提供了一种通过 WS-Security 来表示 “用户名/密码” 对的标准方法 。密码信息可以以纯文本方式(通常,这种方式只有在同时配置了传输层安全协议(Transport Layer Security,TLS)或者使用 WS-Security 加密时才会在生产中使用 — 但是这种方式确实便于测试)或者 以散列值方式发送。
要在 Metro 上实现一个简单的纯文本格式的 UsernameToken 示例,您需要在 WSDL 服务定义中恰当 定义 WS-Policy/WS-SecurityPolicy。清单 1 展示了 “Metro 简介” 中使用过的一个基础 WSDL 服务 定义的修订版,包含了在从客户端到服务器的请求上要求 UsernameToken 的策略信息。与策略本身一样 , 中的策略引用以粗体显示。
清单 1. 纯文本 UsernameToken WSDL
... ... ... ...
清单 1 WSDL 告诉我们,要访问服务需要进行哪些安全处理。您需要同时在服务器端和客户端向策略 信息中添加 WSDL 自定义扩展,通过用户配置细节表明如何实现安全处理。这些自定义扩展被加入到了 WSDL 中的 组件。下一步,我将向您展示每一端的扩展示例。
客户端应用
在客户端,使用一个名为 wsit-client.xml (这个文件名是固定的)的文件来进行 WSIT 配置。这个 文件必须位于根目录的路径下(不在任何包中),或者在类路径的一个目录的 META-INF 子目录中。而 wsit-client.xml 必须是能直接提供全部 WSDL 服务或通过 引用某个独立的 WSDL 服务定义的 WSDL 文档。无论哪一种方式,WSDL 都必须包含 WS-Policy/WS-SecurityPolicy 的全部要求 和 WSIT 配置扩展。
清单 2 展示了 清单 1 WSDL 中的策略部分,通过添加一个 WSIT 自定义扩展来配置客户端 UsernameToken 支持。在这里,那个自定义扩展是 元素 及其子元素,以粗体显示。两个 子元素定义回调类,第一个定义用户名 (name=”usernameHandler”),第二个定义密码(name=”passwordHandler”)。指定的类必须实现 javax.security.auth.callback.CallbackHandler 接口。
清单 2. 带有 WSIT 客户端扩展的 UsernameToken 策略
在 清单 2 中,所有的回调必须使用相同的类。清单 3 是回调类的代码,作用是检查每个回调请求的 类型并恰当地为其赋值:
清单3. 客户端回调代码
public class UserPassCallbackHandler implements CallbackHandler{ public void handle(Callback[] callbacks) throws UnsupportedCallbackException { for (int i = 0; i < callbacks.length; i++) { if (callbacks[i] instanceof NameCallback) { ((NameCallback)callbacks[i]).setName("libuser"); } else if (callbacks[i] instanceof PasswordCallback) { ((PasswordCallback)callbacks[i]).setPassword("books".toCharArray()); } else { throw new UnsupportedCallbackException(callbacks[i], "Unsupported callback type"); } } }}
您并不是必须 使用回调来设置用户名或密码。如果用户名和密码被赋予的是固定值,您可以直接在 元素中设置它们,方法是使用 default=”yyy”(在这里,属性值即实际 的用户名和密码)来替换 classname=”xxx” 属性。
服务器端应用
在服务器端,WSIT 配置信息需要包含在 WSDL 服务定义中。如 “Metro 简介” 所述,服务 WSDL 的 位置可以在服务 WAR 文件中的 WEB-INF/sun-jaxws.xml 里指定为一个参数。如果不使用 WSIT 特性,则 WSDL 是可选的;在这种情况下,WSDL 将在运行时自动生成。如果使用 WSIT 功能,则 WSDL 是必须的, 并且必须包含为服务所用的特性配置 WSIT 所需的任意自定义扩展元素。清单 4 展示了 清单 1 WSDL 服 务的策略部分,这次添加了一个 WSIT 自定义扩展元素来配置 UsernameToken 支持(以粗体显示):
清单 4. 带有 WSIT 服务器端扩展的 UsernameToken 策略
清单 4 中的服务器端 WSIT 扩展以 元素和 子元素形式表示,指定将作为验证器回调使用的类。清单 5 给出了这个类的代 码,这个类必须实现 com.sun.xml.wss.impl.callback.PasswordValidationCallback.PasswordValidaTor 接口。在这里,它 只是针对固定值检查提供的用户名和密码,但它可以轻松使用一个数据库查询或其他机制替代。
清单5. 服务器回调代码
public class PasswordValidaTor implements PasswordValidationCallback.PasswordValidaTor{ public boolean validate(Request request) throws PasswordValidationException { PasswordValidationCallback.PlainTextPasswordRequest ptreq = (PasswordValidationCallback.PlainTextPasswordRequest)request; return "libuser".equals(ptreq.getUsername()) && "books".equals(ptreq.getPassword()); }}
Metro 策略工具
Metro/WSIT 要求您向 WSDL 文件添加配置信息,就像使用 Axis2/Rampart 一样。这个系列中此前介 绍 Axis2/Rampart 的文章在构建过程中使用了一种特殊的策略工具来根据需要生成经过修改的 WSDL 文 件。本文的示例代码 下载 部分包含一种相似的工具,它根据 Metro/WSIT 的需要而设计。
这个工具就是 com.sosnoski.ws.MergeTool 应用程序,在示例代码的 mergetool 目录中。MergeTool 用于将数据合并到目标 XML 文件中,匹配嵌套的 XML 元素,找到需要合并的数据并在目标文档中确定数 据的合并点。示例程序的 build.xml 使用 MergeTool 将客户端或服务器的 WSIT 配置信息添加到服务的 WSDL 中。如果愿意,您也可以在自己的应用程序中使用 MergeTool — mergetool/readme.txt 文件包含 一些基础的使用说明,您也可以在提供的构建中看到 MergeTool 的使用方法。
如果没有 ,Metro 将使用您的 Web 应用程序容器(提供 servlet 的 Web 服务器)所提供的授权机制。
构建并运行示例代码
在调试示例代码之前,您需要在您的操作系统中下载并且安装一个最新版本的 Metro。您还需要对解 压后的示例代码 下载 根目录下的 build.properties 文件进行一些编辑,把 metro-home 属性值改成您 的 Metro 安装路径。如果您还打算测试一个不同操作系统或端口上的服务器,那么您需要修改 host- name 和 host-port。
要使用已提供的 Ant build.xml 构建示例应用程序,需要对下载代码的根目录和 ant 类型打开控制 台。这将首先调用 JAX-WS wsimport 工具(包含在 Metro 发行版中),然后构建客户端和服务器,最后 把服务器端代码打包为一个 WAR(这个过程将生成包含客户端与服务器 WSIT 配置信息的服务 WSDL 的独 立版本)。注意,包含在 Metro 1.5 中的 wsimport 版本会弹出一条警告信息(因为该工具在处理 WSDL 中嵌套的模式时有一个怪癖):src-resolve: Cannot resolve the name ‘tns:BookInformation’ to a (n) ‘type definition’ component。
这时您可以将 metro-library.war 文件部署到您的测试服务器中,然后在控制台上输入 ant run 来 运行示例客户端。示例客户端将向服务器发送一系列请求,并输出每个请求的简单结果。
在 Metro 中签名与加密
UsernameToken 的简洁性使其成为一个不错的起点,但这并不是 WS-Security 的典型应用。在大多数 情况下,您可能会使用签名,或者加密,或者两者都使用。清单 6 展示了一个修改过的、同时使用签名 与加密的 WSDL 示例(基于 “Axis2 WS-Security 签名和加密” 中的示例 — 请参考那篇文章了解关于 WS-Security 签名与加密技术的详细信息)。WSDL 的策略部分以粗体显示。
清单 6. 签名/加密 WSDL
... ... ... ...
清单 6 WSDL 与先前的 Axis2/Rampart 示例中使用过的 WSDL 的唯一重要区别是:当 X509 证书没有 被包含到一条信息中时,需要向 组件添加一个要求使用拇指指纹引用的策 略,其原因是 Metro 和 Axis2 中引用的默认处理方式不同。
当客户端(在 WS-SecurityPolicy 术语中称为发起者)发送一条信息时,客户端的 X.509 证书也作 为信息的一部分发送(因为 元素上的 sp:IncludeToken=”…/IncludeToken/AlwaysTorecipient” 属性),然后服务器使用该证书进行签名验 证。当服务器对客户端进行应答时,进行加密处理时需要引用那个证书。如果没有指定其他方法, Axis2/Rampart 默认使用一个拇指指纹引用进行证书识别。Metro/WSIT 默认使用另一种方法,称为主体 密匙标识符(subject key identifier,SKI)。Axis2/Rampart 示例中使用的证书的形式并不支持 SKI ,所以它们默认不能用于 Metro/WSIT。向策略中添加 元素 告知 Metro/WSIT 使用拇指指纹引用来代替证书。
这种策略改变使先前的 Axis2/Rampart 示例使用的证书和密匙存储可以在现在的示例中使用。这还使 Axis2/Rampart 客户端示例可以与 Metro/WSIT 服务器一起使用,反之也然,从而作为一种检查互操作性 的便捷方式。如果您进行这种尝试(方法是修改每次传送到测试客户端的目标路径),就会发现大部分消 息可以毫不费力地交换 — 但是在实际操作中有一个问题,这将在下面的 互操作性问题 小节进行讨论。
与 UsernameToken 示例一样,WSIT 需要客户端与服务器上存在针对策略信息的自定义扩展,以便提 供详细的附加配置信息。
客户端应用
清单 7 展示了向 WSDL 策略添加的自定义扩展,用于针对本示例配置客户端处理方式。这些自定义扩 展(以粗体显示)配置密匙存储(包含客户端的私有密匙以及对应的证书)和签名与加密所需的可信存储 (包含服务器证书)。
清单 7. 使用 WSIT 客户端扩展签署并加密策略
...
清单 7 WSIT 自定义扩展提供了访问密匙存储和可信存储(在本例中是同一个文件)所需的全部参数 ,包括访问客户端的私有密匙所需的密码( 元素上的 keypass=”clientpass” 属 性)。也可以使用回调获取密码信息,这将在下节介绍。
已命名的密匙存储和可信存储必须放在类路径目录下的 META-INF 子目录中。也可以对这些文件使用 绝对路径 — 而不是仅仅使用文件名 — 这允许您在文件系统的任意固定地址定位它们。(回想一下,对 于客户端,包含 WSIT 自定义扩展的 WSDL 必须使用固定名称 wsit-client.xml,而且必须在类路径的根 目录下或者类路径根目录下的 META-INF子目录中)。
服务器端应用
添加到 WSDL 的服务器端 WSIT 自定义扩展在清单 8 中展示(同样以粗体显示)。在本例中, 的 keypass 属性给出的是一个类名而不是具体的密码值(像 清单 7 客户端示 例一样)。如果您使用这种方法,被引用的类必须实现 javax.security.auth.callback.CallbackHandler 接口;当该类需要访问秘密密匙的密码时,它将被 WSIT 代码调用。对于 sTorepass 值,您也可以使用相同的技术来指定一个类而不是密码。
清单 8. 使用 WSIT 服务器端扩展签署并加密策略
...
清单 9 展示了这个示例使用的 CallbackHandler 接口的实现:
清单 9. 服务器密匙存储密码回调代码
public class KeysToreAccess implements CallbackHandler{ public void handle( Callback[] callbacks) throws IOException, UnsupportedCallbackException { for (int i = 0; i < callbacks.length; i++) { Callback callback = callbacks[i]; if (callback instanceof PasswordCallback) { ((PasswordCallback)callback).setPassword("serverpass".toCharArray()); } else { throw new UnsupportedCallbackException(callback, "unknown callback"); } } }}
构建并运行示例代码
签名与加密示例使用的 构建步骤 与 UsernameToken 示例相同,但是您必须修改 build.properties 文件以使用 variant-name=signencr(而不是 UsernameToken 示例使用的 username)。
互操作性问题
如果您使用 Axis2/Rampart 客户端与 Metro/WSIT 服务器(或者相反),当客户端尝试添加一本国际 标准书籍编号(International Standard Book Number,ISBN)相同的书时,您可能会遇到问题。在这种 情况下,服务器将返回一个 Fault,而不是通常的 SOAP 响应消息。Axis2/Rampart 1.5.x 发布版正确地 执行了 WSDL 在这里要求的签名与加密处理,但是 Metro/WSIT 1.5 却没有,结果造成客户端出错。这是 WSIT 代码中的错误,在下一个版本的 Metro 中应该会得到更正。
如果您运行版本低一些的 Axis2/Rampart,您可能不会遇到任何问题 — 因为 Rampart 直到 1.5 版 本才出现了这个 bug。
结束语
Metro 对 WS-SecurityPolicy 的 WSIT 支持既允许直接配置用户名和密码等参数(包括密钥存储和私 有密钥密码),也可以根据需要通过回调来设置这些值。它还允许您选择使用 servlet 容器的授权处理 机制或者您自己的回调来在服务器上验证用户名和密码组合。这种灵活性使得 Metro 能够轻松满足各种 类型的应用程序的需要。Metro 通过多个集成组件提供 WSIT/XWSS WS-Security 支持,而不是像 Axis2 和 Rampart 那样使用一个独立的组件(拥有自身的发布周期,且不同版本的核心组件之间通常不兼容) 。
不足之处是,关于单独使用与直接配置 Metro/WSIT 的信息非常稀少(相对于与 NetBeans IDE 和 Glassfish 应用程序服务器联合使用的相关信息)。许多必须的信息仅仅在博客文章和电子邮件中进行记 录。
接下来的 Java Web 服务 文章将继续讨论 Metro,下次的关注点是它的性能。与 Axis2 相比,Metro 在简单的消息交换中和使用 WS-Security 时的性能如何。
本文配套源码
青春在我的心中是苦涩的又是甘甜的,是精致的又是粗糙的,