Updating user credentials is even easier than validating them. The IdentityManager interface provides the following two methods for updating credentials:

void updateCredential(Account account, Object credential);

void updateCredential(Account account, Object credential, Date effectiveDate, Date expiryDate);

Both of these methods essentially do the same thing; they update a credential value for a specified Account. The second overloaded method however also accepts effectiveDate and expiryDate parameters, which allow some temporal control over when the credential will be valid. Use cases for this feature include implementing a strict password expiry policy (by providing an expiry date), or creating a new account that might not become active until a date in the future (by providing an effective date). Invoking the first overloaded method will store the credential with an effective date of the current date and time, and no expiry date.

Let's take a look at a couple of examples. Here's some code demonstrating how a password can be assigned to user "jsmith":

User user = BasicModel.getUser(identityManager, "jsmith");

identityManager.updateCredential(user, new Password("abcd1234"));

This example creates a digest and assigns it to user "jdoe":

User user = BasicModel.getUser(identityManager, "jdoe");

Digest digest = new Digest();

digest.setRealm("default");

digest.setUsername(user.getLoginName());

digest.setPassword("abcd1234");        

identityManager.updateCredential(user, digest);

For IdentityStore implementations that support multiple credential types, PicketLink provides an optional SPI to allow the default credential handling logic to be easily customized and extended. To get a better picture of the overall workings of the Credential Handler SPI, let's take a look at the sequence of events during the credential validation process when validating a username and password against JPAIdentityStore:

The CredentialHandler interface declares three methods, as follows:

public interface CredentialHandler {

    void setup(IdentityStore<?> identityStore);


    void validate(IdentityContext context, Credentials credentials,

                  IdentityStore<?> identityStore);


    void update(IdentityContext context, Account account, Object credential,

                IdentityStore<?> identityStore, Date effectiveDate, Date expiryDate);


}

The setup() method is called once, when the CredentialHandler instance is first created. Credential handler instantiation is controlled by the CredentialHandlerFactory, which creates a single instance of each CredentialHandler implementation to service all credential requests for that handler. Each CredentialHandler implementation must declare the types of credentials that it is capable of supporting, which is done by annotating the implementation class with the @SupportsCredentials annotation like so:

@SupportsCredentials(

  credentialClass = { UsernamePasswordCredentials.class, Password.class },

  credentialStorage = EncodedPasswordStorage.class

)

public class PasswordCredentialHandler implements CredentialHandler {

Since the validate() and update() methods receive different parameter types (validate() takes a Credentials parameter value while update() takes an Object that represents a single credential value), the @SupportsCredentials annotation must contain a complete list of all types supported by that handler.

Similarly, if the IdentityStore implementation makes use of the credential handler SPI then it also must declare which credential handlers support that identity store. This is done using the @CredentialHandlers annotation; for example, the following code shows how JPAIdentityStore is configured to be capable of handling credential requests for usernames and passwords, X509 certificates and digest-based authentication:

@CredentialHandlers({ PasswordCredentialHandler.class,

          X509CertificateCredentialHandler.class, DigestCredentialHandler.class })

public class JPAIdentityStore implements IdentityStore<JPAIdentityStoreConfiguration>, 

                                         CredentialStore {

PicketLink provides built-in support for the following credential types:

In this section we'll dissect the PasswordCredentialHandler to learn how to create a custom credential handler. The AbstractCredentialHandler abstract class is provided to simplify the process of creating a new credential handler, and is also used by PasswordCredentialHandler as a base class:

Let's start by looking at the class declaration for PasswordCredentialHandler:

@SupportsCredentials(

        credentialClass = {UsernamePasswordCredentials.class, Password.class},

        credentialStorage = EncodedPasswordStorage.class)

public class PasswordCredentialHandler<S extends CredentialStore<?>, 

    V extends UsernamePasswordCredentials, 

    U extends Password>

    extends AbstractCredentialHandler<S, V, U> {

The @SupportsCredentials annotation is used to declare exactly which credential classes are supported by the credential handler (as indicated by the credentialClass annotation member). The supported credential classes include both credentials used to authenticate via the validate() method (i.e. a class that implements the org.picketlink.idm.credential.Credentials interface, in this example UsernamePasswordCredentials) and the actual encapsulated credential value (e.g. org.picketlink.idm.credential.Password). These supported credential classes are also reflected in the generic type declaration of the class itself - the V and U types in the code above. The credentialStorage annotation member declares the storage class used to persist the necessary state for the credential. The storage class must implement the org.picketlink.idm.credential.storage.CredentialStorage interface.

The setup() method is executed only once and is used to perform any required initialization for the credential handler. In the case of PasswordCredentialHandler, the setup() method reads the configuration properties (made available from store.getConfig().getCredentialHandlerProperties()) and uses those property values to initialize the state required for encoding password values.

@Override

public void setup(S store) {

    super.setup(store);


    Map<String, Object> options = store.getConfig().getCredentialHandlerProperties();


    if (options != null) {

        Object providedEncoder = options.get(PASSWORD_ENCODER);


        if (providedEncoder != null) {

            if (PasswordEncoder.class.isInstance(providedEncoder)) {

                this.passwordEncoder = (PasswordEncoder) providedEncoder;

            } else {

                throw new SecurityConfigurationException("The password encoder [" + 

                    providedEncoder + "] must be an instance of " + 

                    PasswordEncoder.class.getName());

            }

        }


        Object renewRandomNumberGeneratorInterval = options.get(

            RENEW_RANDOM_NUMBER_GENERATOR_INTERVAL);


        if (renewRandomNumberGeneratorInterval != null) {

            this.renewRandomNumberGeneratorInterval = Integer.valueOf(

                renewRandomNumberGeneratorInterval.toString());

        }


        Object secureRandomProvider = options.get(SECURE_RANDOM_PROVIDER);


        if (secureRandomProvider != null) {

            this.secureRandomProvider = (SecureRandomProvider) secureRandomProvider;

        } else {

            Object saltAlgorithm = options.get(ALGORITHM_RANDOM_NUMBER);


            if (saltAlgorithm == null) {

                saltAlgorithm = DEFAULT_SALT_ALGORITHM;

            }


            Object keyLengthRandomNumber = options.get(KEY_LENGTH_RANDOM_NUMBER);


            if (keyLengthRandomNumber == null) {

                keyLengthRandomNumber = Integer.valueOf(0);

            }


            this.secureRandomProvider = new DefaultSecureRandomProvider(

                saltAlgorithm.toString(), 

                Integer.valueOf(keyLengthRandomNumber.toString()));

        }

    }


    this.secureRandom = createSecureRandom();

}

The credential validation logic is defined by the validateCredential() method. This method (which the parent AbstractCredentialHandler class declares as an abstract method) checks the validity of the credential value passed in and either returns true if the credential is valid or false if it is not. The validateCredential() method is a convenience method which delegates much of the boilerplate code required for credential validation to AbstractCredentialHandler, allowing the subclass to simply define the bare minimum code required to validate the credential. If you were to implement a CredentialHandler without using AbstractCredentialHandler as a base class, you would instead need to implement the validate() method which in general requires a fair bit more code.

@Override

protected boolean validateCredential(final CredentialStorage storage, 

    final V credentials) {

    EncodedPasswordStorage hash = (EncodedPasswordStorage) storage;


    if (hash != null) {

        String rawPassword = new String(credentials.getPassword().getValue());

        return this.passwordEncoder.verify(saltPassword(rawPassword, 

            hash.getSalt()), hash.getEncodedHash());

    }


    return false;

}

The update() method (in contrast to validateCredential) is defined by the CredentialHandler interface itself, and is used to persist a credential value to the backend identity store. In PasswordCredentialHandler this method creates a new instance of EncodedPasswordStorage, a CredentialStorage implementation that represents a password's hash and salt values. The salt value in this implementation is randomly generated using the configured property values, and then used to encode the password hash. This value is then stored by calling the store.storeCredential() method.

@Override

public void update(IdentityContext context, Account account, U password, S store,

                   Date effectiveDate, Date expiryDate) {


    EncodedPasswordStorage hash = new EncodedPasswordStorage();


    if (password.getValue() == null || isNullOrEmpty(password.getValue().toString())) {

        throw MESSAGES.credentialInvalidPassword();

    }


    String rawPassword = new String(password.getValue());


    String passwordSalt = generateSalt();


    hash.setSalt(passwordSalt);

    hash.setEncodedHash(this.passwordEncoder.encode(saltPassword(rawPassword, 

        passwordSalt)));


    if (effectiveDate != null) {

        hash.setEffectiveDate(effectiveDate);

    }


    hash.setExpiryDate(expiryDate);


    store.storeCredential(context, account, hash);

}