[CONF] Apache CXF Documentation: WS-SecurityPolicy (page edited)

Placed a full Spring config file to show how policies are added--concerned this was not obvious for most users.

CXF 2.2 introduced support for using WS-SecurityPolicy to configure WSS4J instead of the custom configuration documented on the WS-Security page. However, all of the "background" material on the WS-Security page still applies and is important to know. WS-SecurityPolicy just provides an easier and more standards based way to configure and control the security requirements. With the security requirements documented in the WSDL as WS-Policy fragments, other tools such as .NET can easily know how to configure themselves to inter-operate with CXF services.

Note: at this point, WS-SecurityPolicy support is ONLY available for "WSDL first" scenarios. The WS-SecurityPolicy fragments can only be pulled from WSDL. In the future, we plan to enable various code first scenarios as well, but at this time, only WSDL first is available.

Enabling WS-SecurityPolicy

In CXF 2.2, if the cxf-rt-ws-policy and cxf-rt-ws-security modules are available on the classpath, the WS-SecurityPolicy stuff is automatically enabled. Since the entire security runtime is policy driven, the only requirement is that the policy engine and security policies be available.

If you are using the full "bundle" jar, all the security and policy stuff is already included.

Policy description

With WS-SecurityPolicy, the binding and/or operation in the wsdl references a WS-Policy fragment that describes the basic security requirements for interacting with that service. The WS-SecurityPolicy specification allows for specifying things like asymmetric/symmetric keys, using transports (https) for encryption, which parts/headers to encrypt or sign, whether to sign then encrypt or encrypt then sign, whether to include timestamps, whether to use derived keys, etc... Basically, it describes what actions are necessary to securely interact with the service described in the WSDL.

However, the WS-SecurityPolicy fragment does not include "everything" that is required for a runtime to be able to able to create the messages. It does not describe things such as locations of key stores, user names and passwords, etc... Those need to be configured in at runtime to augment the WS-SecurityPolicy fragment.

Configuring the extra properties

With CXF 2.2, there are several extra properties that may need to be set to provide the additional bits of information to the runtime:

ws-security.username	The username used for UsernameToken policy assertions
ws-security.password	The password used for UsernameToken policy assertions. If not specified, the callback handler will be called.
ws-security.callback-handler	The WSS4J security CallbackHandler that will be used to retrieve passwords for keystores and UsernameTokens.
ws-security.signature.properties	The properties file/object that contains the WSS4J properties for configuring the signature keystore and crypto objects
ws-security.encryption.properties	The properties file/object that contains the WSS4J properties for configuring the encryption keystore and crypto objects
ws-security.signature.username	The username or alias for the key in the signature keystore that will be used. If not specified, it uses the the default alias set in the properties file. If that's also not set, and the keystore only contains a single key, that key will be used.
ws-security.encryption.username	The username or alias for the key in the encryption keystore that will be used. If not specified, it uses the the default alias set in the properties file. If that's also not set, and the keystore only contains a single key, that key will be used.
ws-security.signature.crypto	Instead of specifying the signature properties, this can point to the full WSS4J Crypto object. This can allow easier "programmatic" configuration of the Crypto information."
ws-security.encryption.crypto	Instead of specifying the encryption properties, this can point to the full WSS4J Crypto object. This can allow easier "programmatic" configuration of the Crypto information."

Note: for Symmetric bindings that specify a protection token, the ws-security-encryption properties are used.

Configuring via Spring

The properties are easily configured as client or endpoint properties--use the latter for web service provider configuration:

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jaxws="http://cxf.apache.org/jaxws"
    xsi:schemaLocation="http://www.springframework.org/schema/beans 
    http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
    http://cxf.apache.org/jaxws 
    http://cxf.apache.org/schemas/jaxws.xsd">

<jaxws:client name="{http://cxf.apache.org}MyService" createdFromAPI="true">
    <jaxws:properties>
        <entry key="ws-security.username" value="Alice"/>
        <entry key="ws-security.callback-handler" value="interop.client.KeystorePasswordCallback"/>
        <entry key="ws-security.signature.properties" value="etc/alice.properties"/>
        <entry key="ws-security.encryption.properties" value="etc/bob.properties"/>
    </jaxws:properties>
</jaxws:client>

</beans>

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jaxws="http://cxf.apache.org/jaxws"
    xsi:schemaLocation="http://www.springframework.org/schema/beans 
    http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
    http://cxf.apache.org/jaxws 
    http://cxf.apache.org/schemas/jaxws.xsd">

   <jaxws:endpoint 
      id="MyService"
      address="https://localhost:9001/MyService" 
      serviceName="interop:MyService"
      endpointName="interop:MyServiceEndpoint"
      implementor="com.foo.MyService">
        
      <jaxws:properties>
         <entry key="ws-security.username" value="Alice"/>
         <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
      </jaxws:properties> 
     
   </jaxws:endpoint> 
</beans>

Configuring via API's

Configuring the properties for the client just involves setting the properties in the clients RequestContext:

Map<String, Object> ctx = ((BindingProvider)port).getRequestContext();
ctx.put("ws-security.ws-security.encryption.properties", properties);
port.echoString("hello");