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

void updateCredential(Agent agent, Object credential);

void updateCredential(Agent agent, Object credential, Date effectiveDate, Date expiryDate);

Both of these methods essentially do the same thing; they update a credential value for a specified Agent (or User). 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.

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

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 = identityManager.getUser("jsmith");

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

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

User user = identityManager.getUser("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(SecurityContext context, Credentials credentials, 

                  IdentityStore<?> identityStore);


    void update(SecurityContext context, Agent agent, 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({ UsernamePasswordCredentials.class, Password.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 {

This section describes each of the built-in credential handlers, and any configuration parameters that may be set for them. Specific credential handler options can be set when creating a new IdentityConfiguration. Configured options are always specific to a particular identity store configuration, allowing different options to be specified between two or more identity stores. The IdentityStoreConfiguration interface provides a method called getCredentialHandlersConfig() that provides access to a Map which allows configuration options to be set for the identity store's credential handlers:

public interface IdentityStoreConfiguration {

    Map<String, Object> getCredentialHandlerProperties();

}

To gain access to the IdentityStoreConfiguration object before PicketLink is initialized, there are a couple of options. The first option is to provide an IdentityConfiguration object itself via a producer method.