Note: this article has been updated to include changes introduced in GateIn 3.3.0. For older versions of GateIn which support WS-Security with WSRP, please see the older version of this article https://community.jboss.org/wiki/GateInWSRPAndWebServiceSecurity/version/2

Portlets may present different data or options depending on the currently authenticated user. For remote portlets, this means having to propagate the user credentials from the consumer back to the producer in a safe and secure manner. The WSRP specification does not directly specify how this should be accomplished, but delegates this work to the existing WS-Security standards.

This article will present the required steps to configure a GateIn producer and consumer to use ws-security to propagate credentials between the servers.

Important Notes

Encryption

You will want to encrypt the credentials being sent between the consumer and producer, otherwise they will be sent in plain text and could be easily intercepted. You can either configure WS-Security to encrypt and sign the SOAP messages being sent, or secure the transport layer by using an https endpoint. Failure to encrypt the soap message or transport layer will result in the username and password being sent in plain text. Use of encryption is strongly recommended.

Credentials

When the consumer sends the user credentials to the producer, it is sending the credentials for the currently authenticated user in the consumer. This makes signing in to remote portlets transparent to end users, but also requires that the producer and consumer use the same credentials. This means that the username and password must be the same and valid on both servers.

The recommended approach for this situation would be to use a common ldap configuration. LDAP configuration is beyond the scope of this article, please see the GateIn user guide on how to configure GateIn to use LDAP (http://www.jboss.org/gatein/documentation).

For the simple examples in this article we will not be using ldap. For an out of the box GateIn configuration, the default users should work as they use the same default passwords.

WS-Security Configuration

GateIn uses JBossWS to handle ws-security. Please see the WS-Security section of the JBoss AS 5 Administration and Configuration Guide for indepth configuration options. Please note that since the consumer passes its credentials to the producer, the consumer will act at the wss client and the producer will act as the wss server.

The JBossWS configuration files for the consumer and producer are located in the gatein configuration directory.

Note: these configuration files may not exist by default. If they do not exist, you will need to add them.

For example, in the default GateIn configuration, they should be located at:

server/default/conf/gatein/gatein-wsse-consumer.xml

server/default/conf/gatein/gatein-wsse-producer.xml

GateIn Configuration

WSRP Producer

Other than the JBossWS configuration files mentioned above, no other configuration changes should be necessary for the producer.

WSRP Consumer

In the WSRP Configuration portlet, in the consumer configuration options, you will need to check the 'Enable WS Security' checkbox if you wish to send the user credentials to the producer.

Note: If you wish to use ws-security to just encrypt the communication between the producer and consumer, and not for use identity propagation,  then you will not need to enable this option.

Sample Step by Step Configuration with UsernameToken

The following is a very simple step by step configuration on how to setup and use ws-security with wsrp.

The example will not cover how to setup or use an ldap server or a common authentication mechanism. It will only work with users who exist on both servers and who use the same password (for example the default GateIn users). For a proper configuration you will need to configure ldap or use a common authentication mechanism between the servers. This is beyond the scope of this article.

The example will use the most simple way of passing credentials between the servers, that is the UsernameToken profile. It will not cover using other token options, encrypting the soap message, or signing the soap message. For these topics please refer to the JBoss AS 5 and Native JBossWS documentation.

Initial Server Configuration

For this example we will create two separate servers running on the same machine. Follow similar instructions to configure against separate machine running across a network.

Configuring the Producer

From within the server directory of GateIn, we will create a new server configuration for the producer.

cp -r default producer

We will now need to configure the producer's JBossWS configuration files to use a UsernameToken configuration.

Create the producer configuration file, gatein-wsse-producer.xml, in the server/producer/conf/gatein directory with the following content:

          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.jboss.com/ws-security/config 
            http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">

   
   
     
   

You will also need to configure the producer to expose its services over https. Doing this will encrypt the credentials being sent between the servers. Please see the Configure WSRP for use over SSL wiki article for how to configure wsrp with https. Failure to use https will mean the usernames and passwords can be easily intercepted.

Configuring the Consumer

From within the server directory of GateIn, we will create a new server configuration for the consumer.

cp -r default consumer

We will now need to configure the consumer's JBossWS configuration files to use a UsernameToken configuration.

Create the producer configuration file, gatein-wsse-consumer.xml, in the server/consumer/conf/gatein directory with the following content:

<jboss-ws-security xmlns="http://www.jboss.com/ws-security/config" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.jboss.com/ws-security/config 
            http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">
 
   <!--  Configuration for the GateIn WSRP Consumer WS-Security -->
   <config>
     <username/>
   </config>
</jboss-ws-security>

Starting the Servers

Start the producer server

./run.sh -c producer

Start the consumer server (using a different port configuration since on the same machine in this example)

./run.sh -c consumer -Djboss.service.binding.set=ports-01

Access the consumer, which is now located at http://localhost:8180/portal, and from the WSRP Configuration Admin create a new consumer for making sure to use https for the Producer WSDL URL (eg. https://localhost:8080/wsrp-producer/v2/MarkupService?wsdl) and to have the Enable WS Security checkbox active.

Portlets now accessed over this consumer will have its credentials sent to the producer using ws-security over https.