WS-SecurityPolicy
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.
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
There are several extra properties that may need to be set to provide the additional bits of information to the runtime. Note that you should check that a particular property is supported in the version of CXF you are using.
User properties
ws-security.username |
The user's name. It is used differently by each of the WS-Security functions, see here for more information. |
ws-security.password |
The user's password when "ws-security.callback-handler" is not defined. It is currently only used for the case of adding a password to a UsernameToken. |
ws-security.signature.username |
The user's name for signature. It is used as the alias name in the keystore to get the user's cert and private key for signature. See here for more information. |
ws-security.encryption.username |
The user's name for encryption. It is used as the alias name in the keystore to get the user's public key for encryption. See here for more information. |
Callback Class and Crypto properties
ws-security.callback-handler |
The CallbackHandler implementation class used to obtain passwords. |
ws-security.saml-callback-handler |
The SAML CallbackHandler implementation class used to construct SAML Assertions. |
ws-security.signature.properties |
The Crypto property configuration to use for signature, if "ws-security.signature.crypto" is not set instead. |
ws-security.encryption.properties |
The Crypto property configuration to use for encryption, if "ws-security.encryption.crypto" is not set instead. |
ws-security.signature.crypto |
A Crypto object to be used for signature. If this is not defined then "ws-security.signature.properties" is used instead. |
ws-security.encryption.crypto |
A Crypto object to be used for encryption. If this is not defined then "ws-security.encryption.properties" is used instead. |
Boolean configuration tags, e.g. the value should be "true" or "false".
ws-security.validate.token |
Whether to validate the password of a received UsernameToken or not. The default is true. |
ws-security.enableRevocation |
Whether to enable Certificate Revocation List (CRL) checking or not when verifying trust in a certificate. The default value is "false". |
ws-security.username-token.always.encrypted |
Whether to always encrypt UsernameTokens whenever possible. The default is true. |
ws-security.is-bsp-compliant |
Whether to ensure compliance with the Basic Security Profile (BSP) 1.1 or not. The default value is "true". |
ws-security.self-sign-saml-assertion |
Whether to self-sign a SAML Assertion or not. If this is set to true, then an enveloped signature will be generated when the SAML Assertion is constructed. The default is false. |
ws-security.enable.nonce.cache |
Whether to cache UsernameToken nonces. See here for more information. |
ws-security.enable.timestamp.cache |
Whether to cache Timestamp Created Strings. See here for more information. |
Other properties
ws-security.subject.cert.constraints |
This configuration tag is a comma separated String of regular expressions which will be applied to the subject DN of the certificate used for signature validation, after trust verification of the certificate chain associated with the certificate. These constraints are not used when the certificate is contained in the keystore (direct trust). |
ws-security.timestamp.futureTimeToLive |
This configuration tag specifies the time in seconds in the future within which the Created time of an incoming Timestamp is valid. WSS4J rejects by default any timestamp which is "Created" in the future, and so there could potentially be |
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 former for the SOAP client, the latter for the web service provider.
<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}MyPortName"
createdFromAPI="true">
<jaxws:properties>
<entry key="ws-security.callback-handler"
value="interop.client.KeystorePasswordCallback"/>
<entry key="ws-security.signature.properties"
value="etc/client.properties"/>
<entry key="ws-security.encryption.properties"
value="etc/service.properties"/>
<entry key="ws-security.encryption.username"
value="servicekeyalias"/>
</jaxws:properties>
</jaxws:client>
</beans>
For the jaxws:client's name attribute above, use the namespace of the WSDL along with the name attribute of the desired wsdl:port element under the WSDL's service section. (See here and here for an example.)
<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.callback-handler"
value="interop.client.UTPasswordCallback"/>
<entry key="ws-security.signature.properties"
value="etc/keystore.properties"/>
<entry key="ws-security.encryption.properties"
value="etc/truststore.properties"/>
<entry key="ws-security.encryption.username"
value="useReqSigCert"/>
</jaxws:properties>
</jaxws:endpoint>
</beans>
See this blog entry for a more end-to-end example of using WS-SecurityPolicy with X.509 keys.
Configuring via API's
Configuring the properties for the client just involves setting the properties in the client's RequestContext:
Map<String, Object> ctx = ((BindingProvider)port).getRequestContext();
ctx.put("ws-security.encryption.properties", properties);
port.echoString("hello");