| // |
| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| // |
| |
| == Using Apache WSS4J™ |
| |
| This page describes how to use Apache WSS4J. For information about how to |
| configure WSS4J, see the link:config.html[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. |
| |
| === Action based approach |
| |
| 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 |
| http://cxf.apache.org/docs/ws-security.html[WSS4JOutInterceptor] |
| in Apache CXF. The configuration tags are defined in the https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/ConfigurationConstants.java?view=markup[ConfigurationConstants] class (WSHandlerConstants in WSS4J 1.6.x). For a more detailed explanation |
| of the configuration tags, please refer to the link:config.html[configuration] page. The next few paragraphs will |
| describe the most fundamental configuration tags that are used in most |
| cases. |
| |
| ==== Common configuration tags |
| |
| 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 link:configuration.html[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 https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/resources/org/apache/cxf/systest/ws/action/client.xml[file] for more information. |
| |
| ==== Sample Outbound UsernameToken configuration |
| |
| * *Key* - *Value* |
| * action - UsernameToken |
| * user - Alice |
| * passwordCallbackClass - https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/UTPasswordCallback.java[org.apache.cxf.systest.ws.common.UTPasswordCallback] |
| |
| ==== Sample Outbound Signature/Timestamp configuration |
| |
| * *Key* - *Value* |
| * action - Signature Timestamp |
| * signatureUser - alice |
| * passwordCallbackClass - https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/java/org/apache/cxf/systest/ws/common/KeystorePasswordCallback.java[org.apache.cxf.systest.ws.common.KeystorePasswordCallback] |
| * signaturePropFile - https://github.com/apache/cxf/blob/master/systests/ws-security/src/test/resources/alice.properties[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; |
| |
| === WS-SecurityPolicy based approach |
| |
| 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: |
| http://cxf.apache.org/docs/ws-securitypolicy.html[CXF WS-SecurityPolicy configuration] |
| |
| === Standalone approach |
| |
| 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: |
| |
| * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/UsernameTokenTest.java?view=markup[Username Token Test] |
| * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/EncryptionTest.java?view=markup[Encryption Test] |
| * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/SignatureTest.java?view=markup[Signature Test] |
| * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/message/TimestampTest.java?view=markup[Timestamp Test] |
| * https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/saml/SamlTokenTest.java?view=markup[SAML Token Test] |
| |
| === SOAP Stacks |
| |
| ==== Apache CXF |
| |
| http://cxf.apache.org[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: |
| |
| * http://cxf.apache.org/docs/ws-security.html[CXF WS-Security configuration] |
| * http://cxf.apache.org/docs/ws-secureconversation.html[CXF WS-SecureConversation configuration] |
| * http://cxf.apache.org/docs/ws-securitypolicy.html[CXF WS-SecurityPolicy configuration] |
| * http://cxf.apache.org/docs/ws-trust.html[CXF WS-Trust configuration] |
| * http://cxf.apache.org/resources-and-articles.html[CXF Security articles] |
| |
| ==== Apache Rampart/Axis |
| |
| http://axis.apache.org/axis2/java/rampart/[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: |
| |
| * http://axis.apache.org/axis2/java/rampart/developer-guide.html[Rampart developer guide] |
| * http://axis.apache.org/axis2/java/rampart/samples.html[Rampart samples] |
| * http://axis.apache.org/axis2/java/rampart/rampartconfig-guide.html[Rampart configuration guide] |
| * http://axis.apache.org/axis2/java/rampart/articles.html[Rampart articles] |
| |