Providing Client Credentials

Overview

There are essentially two approaches to providing UsernameToken client credentials: you can either set both the username and the password directly in the client's Spring XML configuration; or you can set the username in the client's configuration and implement a callback handler to provide passwords programmatically. The latter approach (by programming) has the advantage that passwords are easier to hide from view.

Client credentials properties

Table 7.2 shows the properties you can use to specify WS-Security username/password credentials on a client's request context in Spring XML.

Table 7.2. Client Credentials Properties

Properties	Description
`ws-security.username`	Specifies the username for UsernameToken policy assertions.
`ws-security.password`	Specifies the password for UsernameToken policy assertions. If not specified, the password is obtained by calling the callback handler.
`ws-security.callback-handler`	Specifies the class name of the WSS4J callback handler that retrieves passwords for UsernameToken policy assertions. Note that the callback handler can also handle other kinds of security events.

Configuring client credentials in Spring XML

To configure username/password credentials in a client's request context in Spring XML, set the ws-security.username and ws-security.password properties as follows:

<beans ... >
    <jaxws:client name="{NamespaceName}LocalPortName"
                  createdFromAPI="true">
        <jaxws:properties>
            <entry key="ws-security.username" value="Alice"/>
            <entry key="ws-security.password" value="abcd!1234"/>
        </jaxws:properties>
    </jaxws:client>
    ...
</beans>

If you prefer not to store the password directly in Spring XML (which might potentially be a security hazard), you can provide passwords using a callback handler instead.

Programming a callback handler for passwords

If you want to use a callback handler to provide passwords for the UsernameToken header, you must first modify the client configuration in Spring XML, replacing the ws-security.password setting by a ws-security.callback-handler setting, as follows:

<beans ... >
    <jaxws:client name="{NamespaceName}LocalPortName"
                  createdFromAPI="true">
        <jaxws:properties>
            <entry key="ws-security.username" value="Alice"/>
            <entry key="ws-security.callback-handler" value="interop.client.UTPasswordCallback"/>
        </jaxws:properties>
    </jaxws:client>
    ...
</beans>

In the preceding example, the callback handler is implemented by the UTPasswordCallback class. You can write a callback handler by implementing the javax.security.auth.callback.CallbackHandler interface, as shown in Example 7.2.

Example 7.2. Callback Handler for UsernameToken Passwords

package interop.client;

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;

import org.apache.ws.security.WSPasswordCallback;

public class UTPasswordCallback implements CallbackHandler {
    
    private Map<String, String> passwords = 
        new HashMap<String, String>();
    
    public UTPasswordCallback() {
        passwords.put("Alice", "ecilA");
        passwords.put("Frank", "invalid-password");
        //for MS clients
        passwords.put("abcd", "dcba");
    }

    public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
        for (int i = 0; i < callbacks.length; i++) {
            WSPasswordCallback pc = (WSPasswordCallback)callbacks[i];

            String pass = passwords.get(pc.getIdentifier());
            if (pass != null) {
                pc.setPassword(pass);
                return;
            }
        }
        
        throw new IOException();
    }
    
    // Add an alias/password pair to the callback mechanism.
    public void setAliasPassword(String alias, String password) {
        passwords.put(alias, password);
    }
}

The callback functionality is implemented by the CallbackHandler.handle() method. In this example, it assumed that the callback objects passed to the handle() method are all of org.apache.ws.security.WSPasswordCallback type (in a more realistic example, you would check the type of the callback objects).

A more realistic implementation of a client callback handler would probably consist of prompting the user to enter their password.

WSPasswordCallback class

When a CallbackHandler is called in a FUSE Services Framework client for the purpose of setting a UsernameToken password, the corresponding WSPasswordCallback object has the USERNAME_TOKEN usage code.

For more details about the WSPasswordCallback class, see org.apache.ws.security.WSPasswordCallback.

The WSPasswordCallback class defines several different usage codes, as follows:

USERNAME_TOKEN: Need the password to fill in or to verify UsernameToken credentials. In other words, this usage code is used both on the client side (to obtain a password to send to the server) and on the server side (to obtain a password in order to compare it with the password received from the client).
DECRYPT: Need a password to get the private key of this identifier (username) from the keystore. WSS4J uses this private key to decrypt the session (symmetric) key.
SIGNATURE: Need the password to get the private key of this identifier (username) from the keystore. WSS4J uses this private key to produce a signature.
KEY_NAME: Need the key, not the password, associated with the identifier. WSS4J uses this key to encrypt or decrypt parts of the SOAP request. Note, the key must match the symmetric encryption/decryption algorithm specified (refer to WSHandlerConstants.ENC_SYM_ALGO).
USERNAME_TOKEN_UNKNOWN: Either an unspecified password type or the password type, passwordText. In these both cases, only the password variable is set. The callback class now may check if the username and password match. If they do not match, the callback class must throw an exception. The exception can be a UnsupportedCallbackException or an IOException.
SECURITY_CONTEXT_TOKEN: Need the key to to be associated with a wsc:SecurityContextToken.
UNKNOWN: Not used by WSS4J.