Contents
Overview
ActiveBPEL Setup
Upgrade Your JCE
.NET Interoperability

WS-Security Using SAML

Overview

The archive for this sample is here.

This sample includes BPEL processes that demonstrate the use of WS-Security features supported by ActiveBPEL Enterprise. The sample is provided to demonstrate the use of policy and the available WS-Security features supported by the ActiveBPEL product.

This sample project is for advanced users. We assume that you are comfortable with the mechanics of deploying a BPEL process using ActiveBPEL Designer and ActiveBPEL Enterprise. The wss-sender process, described below, can be invoked using soapUI or equivalent. A sample soapUI project is included. All of the BPEL, PDD and related files you'll need can be found in the sample.com.activee.wss.zip archive that is included in the sample archive, linked above.

Note that the methods described in this sample do not necessarily represent best security practices for a production environment. It is provided only as an introduction to the use of WS-Security features.

In this sample, wss-sender invokes wss-receiver with the following WSS message security features:

Transport Security:
- SSL (optional)
- HTTP Basic Authentication

Message Security:
- UsernameToken
- Signature with X.509 Certificate
- XML Encryption with RSA 1.5 Key transport and TripleDES data encryption
- XML Signature
- Timestamp

Security Token Propagation with SAML 1.1:
- Read X.509 certificate data from an incoming SOAP Header to get the sender's signing certificate
- Use the certificate to issue a SAML authentication query
- Add a SAML Assertion as a signed Header on another request using dynamic endpoints

The wss-receiver service will only accept the request if it complies with all of the listed security requirements (Signed and Encrypted with a UsernameToken). The X.509 binary security token used to sign the start request is pulled from the SOAP Header using an XPath policy. The token is then mapped into a SAML 1.1 Authentication query.

The SAML service is invoked and we check the value of the status code returned from the SAML Authority. The service replies to the sender using a callback that includes the returned SAML Assertion as a signed SOAP header on the response.

The use of security features is specified in the wss-sender.pdd and wss-receiver.pdd files as policy assertions on each endpoint. Please refer to the user's guide for specifics on the various policy options and their usage.

To run the sample, please update the following for your environment:

Please use the ActiveBPEL Admin Console to add or update the URN mapping for "ae:localhost" to match your environment. For example, set the URN value to "http://localhost:8080/active-bpel/services/${urn.3}" to point to a local development server.
Note that the authentication policy in the .pdd files specifies values for username and password.
Feel free to edit these to match your environment. Note that we have included the password in a CleartextPassword assertion to make editing the value easier for the sample, which we would not recommend for production use.

ActiveBPEL Setup

The WS-Security handlers use private keys and digital certificates stored in a java keystore to sign and encrypt message parts as well as verify identity and trust.

Edit the crypto.properties file found in your ActiveBPEL installation directory. If this file is not present, you may copy the example provided with the sample to this location to run the sample.

The example includes values that match the sample keystore ae.keystore.

The crypto.properties file must be available on the server's classpath.

**Typical server locations for crypto.properties & keystore files**
Server	Directory
Tomcat	$CATALINA_HOME/shared/classes
Weblogic (8 & 9)	$DOMAIN_HOME
JBoss	$JBOSS_HOME/server/$SERVER_DIR/conf (also ensure that this conf directory is before wss4j.jar on the classpath)
WebSphere	$PROFILE_HOME/properties
Sun	$DOMAIN_HOME

The following properties must be set in crypto.properties to match the your environment:

Specify the keystore file to use with your ActiveBPEL server.

This file must be accessible by the server from the file system at the location specified.

org.apache.ws.security.crypto.merlin.file=ae.keystore

Set the keystore type. Typically the values will be either "jks" or "pkcs12", depending on the type of keystore you are using.

org.apache.ws.security.crypto.merlin.keystore.type=pkcs12

Specify the keystore alias of the entry containing a private key used for signing & decryption. If you are unsure of the value, use the java keytool utility to display the contents of your keystore. See Sun's documentation on the keytool command for details on using this tool.

org.apache.ws.security.crypto.merlin.keystore.alias=<alias>

If a password is required to access the keystore, use the property below

org.apache.ws.security.crypto.merlin.keystore.password=<password>

If a password is required to access the private key, use the property below

org.apache.ws.security.crypto.merlin.alias.password=<password>

Upgrade your JCE provider to support all algorithms needed for WSS

The default provider shipped with most JDKs does not support all the algorithms necessary for xml security.

The provider from BouncyCastle (www.bouncycastle.org) does support all necessary algorithms.

Obtain the .jar file and copy into your jre/lib/ext directory to install.

Add a provider entry to jre/lib/security/java.security for the new provider The entry will look something like this:

security.provider.7=org.bouncycastle.jce.provider.BouncyCastleProvider

Also, if you have problems, you may need to update your xmlsec-1.3.0.jar to xmlsec-1.4.1.jar in shared/lib.

.NET Service Interoperability Notes

.NET RFC3280 Compliance

Make sure external .NET services and clients are configured to support the X.509 Subject Key Intentifier algorithm specified by RFC3280. By default, .NET services and clients will use a Windows-specific algorithm for determining the SKI.
Ensure the useRFC3280="true" attribute is set on the <X509> element in web.config.
This switch is supported as of service pack 1 of WSE 2.0.

XML Signature Compliance

ActiveBEPL 2.1 does not support .NET clients that derive signature tokens from the UsernameToken element, rather than use X.509 tokens.