WSS4J Interceptors and WSRP

The WSS4J Interceptors are configured using properties, and as such can be configured using simple property files.

WSRP looks for specific property files to know whether or not in/out interceptors must be added and configured for either consumers or producer. Theses files are located in the standalone/configuration/gatein/wsrp/cxf/ws-security directory of your the JBoss AS 7 home directory. Consumer-specific files are in the consumer subdirectory while producer-specific files should be located in the producer subdirectory. To add and configure a WSS4J interceptor, you just need to add the proper configuration file in the proper directory. If no configuration file is found for a specific interceptor type, then no such interceptor will be added. "In" interceptors are configured using WSS4JInInterceptor.properties files while "out" interceptors are configured using WSS4JOutInterceptor.properties files.

Putting things together, here are the files you need to add to configure each interceptor types for each WSRP side:

Please refer to the CXF or WSS4J documentation for instructions and options available for each type of interceptors.

Custom 'user' option:

user=gtn.current.user

What this option will do is it will set the 'user' property to the currently authenticated user on the consumer.

Custom 'action' option

action=gtn.UsernameToken.ifCurrentUserAuthenticated

If a user is currently authenticated, it will replace the 'gtn.UsernameToken.ifCurrentUserAuthenticated' with 'UsernameToken'. If the current user is an unauthenticated user, 'gtn.UsernameToken.ifCurrentUserAuthenticated' will be removed from the action list. If no other actions are specified, then the WSS4J interceptor will not be added to the consumer. This allows you to only use ws-security when dealing with authenticated users, and not for anonymous users.

Custom PasswordCallbackClass

To set the password for the username token, we need to specify the password in a callback class. See the cxf ws-security documentation for more details (http://cxf.apache.org/docs/ws-security.html).

A special callback class has already been created which handles this for you: CurrentUserPasswordCallback. This class will retrieve the currently authenticated user's password and set this as the password in the callback object.

passwordCallbackClass=org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback

Special GateIn Portal Configuration Options for User Propagation

To properly propagate user information on the producer-side, you will need to use GTNSubjectCreatingInterceptor instead of a regular WSS4JInInterceptor. This GateIn Portal specific "in" interceptor is an extension of the traditional WSS4JInInterceptor and therefore can be configured similarly and accept the same configuration properties. To specify that you want to use the GTNSubjectCreatingInterceptor, please create a property file at standalone/configuration/gatein/wsrp/cxf/ws-security/producer/GTNSubjectCreatingInterceptor.properties instead of the regular WSS4JInInterceptor.properties file.

This Interceptor will handle the ws-security headers and retrieve the users credentials. It will then use these credentials to perform a login on the producer site, thus authenticating the user on the producer and makes the user available to remote portlets.

Custom 'action' option

action=gtn.UsernameToken.ifAvailable

When this option is activated, the interceptor will set the action to 'UsernameToken' when the received SOAP message contains ws-security headers. If no ws-security header is included in the message, then no action is taken and the interceptor is not run. This is useful for dealing with authenticated and unauthentcated users trying to access the producer.

Producer Setup

1. create the following file: standalone/configuration/gatein/wsrp/cxf/ws-security/producer/GTNSubjectCreatingInterceptor.properties

2. set the content of GTNSubjectCreatingInterceptor.properties created in step 1 to:

   action=gtn.UsernameToken.ifAvailable

3. start the producer server

Consumer Setup

1. create the following file: standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JOutInterceptor.properties

2. set the content of the WSS4JOutInterceptor.properties created in step 1 to:

   passwordType=PasswordText
   user=gtn.current.user
   action=gtn.UsernameToken.ifCurrentUserAuthenticated
   passwordCallbackClass=org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback

3. start the consumer server

4. in the WSRP admin portlet, click the 'enable ws-security' checkbox

5. access a remote portlet (for example, the user identity portlet included as an example portlet in GateIn Portal) and verify that the authenticated user is the same as the one on the consumer

Password Callback Class

WSS4J uses a Java class to specify the password when performing any security related actions. For the purpose of these encryption and signing examples, we will use the same password for the producer's and consumer's keystore (wsrpAliasPassword). This simplifies things a bit as it means we can use just one password callback class for both the producer and consumer.

Example test.TestCallbackHandler class:

package test;
 
import java.io.IOException;
 
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
 
import org.apache.ws.security.WSPasswordCallback;
import org.gatein.wsrp.wss.cxf.consumer.CurrentUserPasswordCallback;
 
public class TestCallbackHandler implements CallbackHandler
{
 
    @Override
    public void handle(Callback[] callbacks) throws IOException,
            UnsupportedCallbackException
    {
 
        //First check if we have any user name token call backs to add.
        //NOTE: only needed if using username tokens, and you want the currently authenticated users password added
        CurrentUserPasswordCallback currentUserPasswordCallback = new CurrentUserPasswordCallback();
        currentUserPasswordCallback.handle(callbacks);
 
        for (Callback callback: callbacks)
        {
            if (callback instanceof WSPasswordCallback)
            {
                WSPasswordCallback wsPWCallback = (WSPasswordCallback)callback;
                // since the CurrentUserPasswordCallback already handles the USERNAME_TOKEN case, we don't want to set it in this case
                if (wsPWCallback.getUsage() != WSPasswordCallback.USERNAME_TOKEN)
                {
                    wsPWCallback.setPassword("wsrpAliasPassword");
                }
            }
        }
    }
}

You can see a working example of a CallbackHandler implentation at https://github.com/gatein/gatein-wsrp/tree/master/examples/wss-callback

Configuring the Keystores

1. Generate the producer's private encryption keys

   keytool -genkey -alias producerAlias -keypass wsrpAliasPassword -keystore producer.jks -storepass keyStorePassword -dname "cn=producerAlias" -keyalg RSA

2. Export the producer's public key

   keytool -export -alias producerAlias -file producerkey.rsa -keystore producer.jks -storepass keyStorePassword

3. Generate the consumer's private encryption keys

   keytool -genkey -alias consumerAlias -keypass wsrpAliasPassword -keystore consumer.jks -storepass keyStorePassword -dname "cn=consumerAlias" -keyalg RSA

4. Export the consumer's public key

   keytool -export -alias consumerAlias -file consumerkey.rsa -keystore consumer.jks -storepass keyStorePassword

5. Import the consumer's public key into the producer's keystore

   keytool -import -alias consumerAlias  -file consumerkey.rsa -keystore producer.jks -storepass keyStorePassword -noprompt

6. Import the producer's public key into the consumer's keystore

   keytool -import -alias producerAlias  -file producerkey.rsa -keystore consumer.jks -storepass keyStorePassword -noprompt

7. Copy the producer.jks file to the standalone/configuration/gatein/wsrp/cxf/ws-security/producer directory on the producer

8. Copy the consumer.jks file to the standalone/configuration/gatein/wsrp/cxf/ws-security/consumer directory on the consumer

Configuring the Producer

1. Create standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JInInterceptor.properties with the following content. This will configure the incoming message between the producer and the consumer

   action=Signature Encrypt Timestamp
   signaturePropFile=producer-security.properties
   decryptionPropFile=producer-security.properties
   passwordCallbackClass=test.TestCallbackHandler

2. Create standalone/configuration/gatein/wsrp/cxf/ws-security/producer/WSS4JOutInterceptor.properties with the following content. This will configure the outgoing message between the producer and the consumer

   action=Signature Encrypt Timestamp
   signaturePropFile=producer-security.properties
   encryptionPropFile=producer-security.properties
   passwordCallbackClass=test.TestCallbackHandler
   user=producerAlias
   encryptionUser=consumerAlias
   signatureUser=producerAlias

3. Create standalone/configuration/gatein/wsrp/cxf/ws-security/producer/producer-security.properties with the following content:

   org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
   org.apache.ws.security.crypto.merlin.keystore.type=jks
   org.apache.ws.security.crypto.merlin.keystore.password=keyStorePassword
   org.apache.ws.security.crypto.merlin.file=producer.jks

4. The passwordCallbackClass property in these configuration files needs to match the fully qualified name of your CallbackHandler implementation class. In our case, it is test.TestCallbackHandler.

Configuring the Consumer

1. Create standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JOutInterceptor.properties with the following content. This will configure the outgoing message between the consumer and the producer

   action=Signature Encrypt Timestamp
   signaturePropFile=consumer-security.properties
   encryptionPropFile=consumer-security.properties
   passwordCallbackClass=test.TestCallbackHandler
   user=consumerAlias
   encryptionUser=producerAlias
   signatureUser=consumerAlias

2. Create standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/WSS4JInInterceptor.properties with the following content. This will configure the incoming message between the consumer and the producer

   action=Signature Encrypt Timestamp
   signaturePropFile=consumer-security.properties
   decryptionPropFile=consumer-security.properties
   passwordCallbackClass=test.TestCallbackHandler

3. Create standalone/configuration/gatein/wsrp/cxf/ws-security/consumer/consumer-security.properties with the following content:

   org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
   org.apache.ws.security.crypto.merlin.keystore.type=jks
   org.apache.ws.security.crypto.merlin.keystore.password=keyStorePassword
   org.apache.ws.security.crypto.merlin.file=consumer.jks

4. The passwordCallbackClass property in these configuration files needs to match the fully qualified name of your CallbackHandler implementation class. In our case, it is test.TestCallbackHandler.

Configure the Producer

Follow the steps outlined in the Sample Configuration Securing the Endpoints using Encryption and Signing section but make the following changes:

1. rename the WSS4JInInterceptor.properties file to GTNSubjectCreatingInterceptor.properties

2. set the action property in GTNSubjectCreatingInterceptor.properties as:

   action= gtn.UsernameToken.ifAvailable Signature Encrypt Timestamp

3. set the passwordType in GTNSubjectCreatingInterceptor.properties as:

   passwordType=PasswordText

Configure the Consumer

Follow the steps outlined in the Sample Configuration Securing the Endpoints using Encryption and Signing section but make the following changes:

1. set the action property in WSS4JOutInterceptor.properties as:

   action=gtn.UsernameToken.ifCurrentUserAuthenticated Signature Encrypt Timestamp

2. set the user in the WSS4JOutInterceptor.properties as:

   user=gtn.current.user

3. set the passwordType in the WSS4JOutInterceptor.properties as:

   passwordType=PasswordText