Introduction

Overview

This page is a description of how to make people picker secure. All these steps have been built into the publicly available People Picker. We document them here for developers of other web services and to make debugging problems with People Picker easier.

Diagram

Client                           Server
(a java program that   ---(1)-->  (an axis web
uses a jar full of     <--(2)---  service)
axis code to connect
to the service)

Description

People Picker is composed of two service/client communication channels. In one, idp-pp is the server and fed-pp is the client and in the other, fed-pp is the server and web-pp is the client. Both of these channels are being secured in the same manner.

On the current β, only the service-to-client data is encrypted (2 on the above diagram). The client to server data is not encrypted because it is not sensitive. However, the methods here can be readily mirrored to create two-way secure communication. Indeed, we intend to have two-way secure communication in the 1.0 release of People Picker.

We are using public/private key encryption to secure the data. All data coming out of a server is encrypted with the client's public key and the client then decrypts it. Servers can ensure the data stays secure by only releasing data to known clients using their trusted private key. No matter who then gets access to the data, only the trusted client can pull it apart and see it.

Technology

Axis2 and Rampart

All of people picker is build with axis2, and we can use the axis2 implementation of wss4j (rampart) to do all the heavy lifting for us. The basic steps for using rampart (which we will give more detail on soon) are:

• Download Rampart
• Take all the .mar files and put them in you axis modules directory.
• Take all files in lib and put them in your axis lib directory.
• Set rampart parameters
• Turn rampart on.

On the server

Since the server runs in a full-blown axis2 environment, the above steps are straightforward. You use the actual axis modules and lib directories, and use the axis2 manager to enable rampart on the service. The only difficult part is the parameters.

You need to tell rampart what mode to work in, we do this by adding the following to the service.xml file on the server.

<module ref="rampart"/>
<parameter name="OutflowSecurity">
  <action>
    <items>Encrypt</items>
    <encryptionUser>XXXX</encryptionUser>
    <encryptionPropFile>service.properties</encryptionPropFile>
  </action>
</parameter>

Where XXXX is the alias under which you imported the client's RSA certificate into your keystore.

Notice that these setting reference a properties file, you need to write this and put it in the root of the aar file you have the service in.

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=XXXX
org.apache.ws.security.crypto.merlin.file=wskeys.jks

Here, XXXX is the password needed to extract the RSA certificate from the keystore.

All this talk of keystores and we don't have one yet. You need to create a java keystore (in the above properties file, we have said it is wskeys.jks, so we better call it that), import the RSA certificate into it, and put it also in the root of the aar.

On the client.

The client accesses the service by calling methods we provided in a service-connector.jar. This jar is created from the axis2 code that is generated for the service. In this jar is actually a full axis2 implementation. To get this code to talk to a secure server, we need to modify some code in the connector part of the server.

For example, in fed-pp we have added the following code to to the class that exposes service functionality

public FedPPService(String uri)
    {
        ConfigurationContext ctx = null;
        try{
            ctx = ConfigurationContextFactory.createConfigurationContextFromFileSystem(".", "conf/axis2.xml");
        }catch(AxisFault e){
            logger.severe("Could not find axis2.xml, reverting to no config");
        }
        //create the stub
        try{
            if (ctx!=null)
                stub = new FederatedPeoplePickerStub(ctx, uri);
            else
                stub = new FederatedPeoplePickerStub(uri);

Here, the stub is created with a configuration context if we can find one. Now, the jar that results from this does not know where it will be deployed, so it does not know where this configuration context might be. Thus there is also code that allows you to tell the constructor where to go looking. Regardless, this configuration context must be present wherever the jar is being used if you want to be able to set rampart parameters.

It is within this configuration context that axis2 code hidden in the jar will go looking for information about its setup and its modules. Thus it is in here that you must put the rampart modules (within a directory called modules) and a conf directory containing the axis2 configuration file (in our example this file is called axis2.xml).

In this configuration file you can turn on rampart and you can set rampart's parameters, which, for accepting a secure connection encrypted with your private key, will look like

<parameter name="InflowSecurity">
      <action>
        <items>Encrypt</items>
        <passwordCallbackClass>au.edu.mq.melcoe.mams.webpp.PWCB</passwordCallbackClass>
        <decryptionPropFile>client.properties</decryptionPropFile>
       </action>
    </parameter>

Notice that this requires another properties file which must be in the classpath

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=YYYYYY
org.apache.ws.security.crypto.merlin.file=client.jks

which requires your private key to be in a keystore also in the classpath. Since it is a private key that we are trying to retrieve, we need an extra password (YYYYYY) to get into this. In wss4j this must be accessed by calling a password callback class. We already told rampart where to look in the axis2.xml settings, so we only need to ensure this class exists and returns the correct string.

*Done!*