This page describes how to use Apache WSS4J. For information about how to configure WSS4J, see the configuration page. WSS4J can essentially be used in three different ways. For information about using WSS4J with a SOAP stack, see the sections on Apache CXF and Apache Rampart/Axis.
Action based approach: WSS4J offers an "Action" based approach to applying WS-Security to a SOAP request or response, in conjunction with a SOAP stack.
WS-SecurityPolicy based approach: WSS4J can be configured for a SOAP request/response via WS-SecurityPolicy, in conjunction with a SOAP Stack. This is the recommended approach.
Standalone approach: WSS4J offers a low-level (DOM) API to construct/sign/encrypt/etc. tokens directly.
The WSHandler class in WSS4J is designed to configure WSS4J to secure an outbound SOAP request, by parsing configuration that is supplied to it via a subclass. Typically a web services stack that uses WSS4J for WS-Security will subclass WSHandler. An example of a subclass is the WSS4JOutInterceptor in Apache CXF. The configuration tags are defined in the ConfigurationConstants class (WSHandlerConstants in WSS4J 1.6.x). For a more detailed explanation of the configuration tags, please refer to the configuration page. The next few paragraphs will describe the most fundamental configuration tags that are used in most cases.
The "Action" based approach to using Apache WSS4J involves explicitly telling WSS4J what WS-Security functionality to perform on a request, by configuring the stack specific WSHandler implementation with the required properties. On the receiving side, the "actions" that are configured are matched against what was processed in the security header, and an error is thrown if they do not match (in some order). Typical actions include "UsernameToken, "Signature", "Encrypt", "Timestamp, "SAMLTokenSigned", etc.
After specifying the action to perform on a request, the next task is typically to specify the "user". The "user" can be either the username to insert into a UsernameToken, or the keystore alias to use for either signature or encryption. If you are configuring more than one of these actions, the "signatureUser" and "encryptionUser" configuration tags override the more general "user" tag. The next task is often to specify a CallbackHandler implementation to use to retrieve passwords. On the sending side, this is used to retrieve a password to insert into a UsernameToken and to decrypt a private key from a keystore for Signature. On the receiving side, it is used to retrieve a password to validate a received UsernameToken, and to decrypt a private key from a keystore to use for decryption.
The next task is to specify a Crypto implementation if you are using Signature or Encryption. See the configuration page for more information on the Crypto interface. Typically, it is configured in a Crypto properties file, which specifies the Crypto implementation to use, as well as the keystore location, default alias/password, etc. For signature, the path of this properties file can be referred to by the tag "signaturePropFile" and "encryptionPropFile" for outbound request, and "signatureVerificationPropFile" and "decryptionPropFile" for inbound requests". How signing keys/certificates are referenced from a Signature can be controlled via the "signatureKeyIdentifier" configuration tag. This defaults to "IssuerSerial", but could be "DirectReference", "Thumbprint", etc. The "encryptionKeyIdentifier" tag performs the same function for encryption.
Finally, the Elements to sign or encrypt can be specified by the "signatureParts" and "encryptionParts" configuration tags. Both default to the SOAP Body. The value of signatureParts/encryptionParts is a list of semi-colon separated values that identify the elements to sign/encrypt. The value is of the format of an encryption mode specifier, and a namespace URI, each inside a pair of curly brackets, and then the local name of the Element. For example, "{Content}{http://example.org/paymentv2}CreditCard;". The encryption modifier can be either "Content" or "Element" and only applies to encryption.
Here are some sample configuration values for various actions, as taken from some CXF system tests. The constructor of the WSS4JOutInterceptor/WSS4JInIntereptor interceptors in CXF takes a map of String/Object pairs which correspond to the key/value pairs given in the tables below. See the CXF configuration file for more information.
Key - Value
action - UsernameToken
user - Alice
passwordCallbackClass - org.apache.cxf.systest.ws.common.UTPasswordCallback
Key - Value
action - Signature Timestamp
signatureUser - alice
passwordCallbackClass - org.apache.cxf.systest.ws.common.KeystorePasswordCallback
signaturePropFile - alice.properties
signatureKeyIdentifier - DirectReference
signatureParts - {}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{}{http://schemas.xmlsoap.org/soap/envelope/}Body;
The recommended way of applying WS-Security to your web services is to use WS-SecurityPolicy. The WS-SecurityPolicy specification defines a set of WS-Policy expressions that can be used to define the security requirements of a web service. Typically one or more policies are attached to the WSDL of a service, which conveys the security requirements of the service to the client. A WS-SecurityPolicy aware stack such as Apache CXF or Apache Axis/Rampart can parse the policies and configure WSS4J appropriately. This greatly simplifies things for the user, who then only has to supply some basic information about which users, CallbackHandlers, Crypto property files, etc. to use.
For more information on using WS-SecurityPolicy with WSS4J, please see CXF’s WS-SecurityPolicy page, or go to the SOAP stack sections below: CXF WS-SecurityPolicy configuration
Apache WSS4J provides a set of APIs to implement WS-Security functionality on a SOAP message. It is possible to use these APIs directly in a standalone manner, although it is far more common to use either the "Action" or WS-SecurityPolicy based approaches. This functionality is only available for the DOM code. The best way of finding out how to do this is to take a look at the test sources. For example:
Apache CXF is an open-source web services stack. CXF uses WSS4J to perform the core WS-Security functionality, and provides extended security functionality based around the WS-SecurityPolicy, WS-SecureConversation and WS-Trust specifications. More information:
Apache Rampart is the security module for the Axis2 web services stack. Rampart uses WSS4J to perform the core WS-Security functionality, and provides extended security functionality based around the WS-SecurityPolicy, WS-SecureConversation and WS-Trust specifications. Note that support for Apache Axis1 via the WSS4J 1.5.x series of releases is no longer supported. More information: