PicketLink Reference Documentation

The Identity Management module defines the base identity model; a collection of interfaces and classes that represent the identity constructs (such as users, groups and roles) used throughout PicketLink (see the Identity Management chapter for more details). As such, it is a required module and must always be included in any application deployments that use PicketLink for security. It also provides a uniform API for managing the identity objects within your application. The Identity Management module has been designed with minimal dependencies and may be used in a Java SE environment, however the recommended environment is Java EE in conjunction with the base module.

Libraries are as follows:

The Federation module is an optional module that implements a number of Federated Identity standards, such as SAML (both version 1.1 and 2.0), WS-Trust and OpenID.

Let's take a closer look at an extremely simple example of an Authenticator. The following code demonstrates an Authenticator implementation that simply tests the username and password credentials that the user has provided against hard coded values of jsmith for the username, and abc123 for the password, and if they match then authentication is deemed to be a success:

@PicketLink

public class SimpleAuthenticator extends BaseAuthenticator {


    @Inject DefaultLoginCredentials credentials;


    @Override

    public void authenticate() {

        if ("jsmith".equals(credentials.getUserId()) &&

                "abc123".equals(credentials.getPassword())) {

            setStatus(AuthenticationStatus.SUCCESS);

            setAccount(new User("jsmith"));

        } else {

            setStatus(AuthenticationStatus.FAILURE);

            FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(

                    "Authentication Failure - The username or password you provided were invalid."));

        }

    }

}

The first thing we can notice about the above code is that the class is annotated with the @PicketLink annotation. This annotation indicates that this bean should be used for the authentication process. The next thing is that the authenticator class extends something called BaseAuthenticator. This abstract base class provided by PicketLink implements the Authenticator interface and provides implementations of the getStatus() and getAccount() methods (while also providing matching setStatus() and setAccount() methods), and also provides an empty implementation of the postAuthenticate() method. By extending BaseAuthenticator, our Authenticator implementation simply needs to implement the authenticate() method itself.

We can see in the above code that in the case of a successful authentication, the setStatus() method is used to set the authentication status to SUCCESS, and the setAccount() method is used to set the user (in this case by creating a new instance of User). For an unsuccessful authentication, the setStatus() method is used to set the authentication status to FAILURE, and a new FacesMessage is created to indicate to the user that authentication has failed. While this code is obviously meant for a JSF application, it's possible to execute whichever suitable business logic is required for the view layer technology being used.

One thing that hasn't been touched on yet is the following line of code:

@Inject DefaultLoginCredentials credentials;

This line of code injects the credentials that have been provided by the user using CDI's @Inject annotation, so that our Authenticator implementation can query the credential values to determine whether they're valid or not. We'll take a look at credentials in more detail in the next section.

If your application needs to support multiple authentication methods, you can provide the authenticator selection logic within a producer method annotated with @PicketLink, like so:

@RequestScoped

@Named

public class AuthenticatorSelector {


    @Inject Instance<CustomAuthenticator> customAuthenticator;

    @Inject Instance<IdmAuthenticator> idmAuthenticator;

    

    private String authenticator;

    

    public String getAuthenticator() {

        return authenticator;

    }

    

    public void setAuthenticator(String authenticator) {

        this.authenticator = authenticator;

    }


    @Produces

    @PicketLink

    public Authenticator selectAuthenticator() {

        if ("custom".equals(authenticator)) {

            return customAuthenticator.get();

        } else {

            return idmAuthenticator.get();

        }

    }

}

This @Named bean exposes an authenticator property that can be set by a user interface control in the view layer. If its value is set to "custom" then CustomAuthenticator will be used, otherwise IdmAuthenticator (the Authenticator used to authenticate using the identity management API) will be used instead. This is an extremely simple example but should give you an idea of how to implement a producer method for authenticator selection.

Credentials are something that provides evidence of a user's identity; for example a username and password, an X509 certificate or some kind of biometric data such as a fingerprint. PicketLink has extensive support for a variety of credential types, and also makes it relatively simple to add custom support for credential types that PicketLink doesn't support out of the box itself.

In the previous section, we saw a code example in which a DefaultLoginCredentials (an implementation of the Credentials interface that supports a user ID and a credential value) was injected into the SimpleAuthenticator bean. The most important thing to know about the Credentials interface in relation to writing your own custom Authenticator implementation is that you're not forced to use it. However, while the Credentials interface is mainly designed for use with the Identity Management API (which is documented in a separate chapter) and its methods would rarely be used in a custom Authenticator, PicketLink provides some implementations which are suitably convenient to use as such, DefaultLoginCredentials being one of them.

So, in a custom Authenticator such as this:

public class SimpleAuthenticator extends BaseAuthenticator {


    @Inject DefaultLoginCredentials credentials;

    

    // code snipped

}

The credential injection is totally optional. As an alternative example, it is totally valid to create a request-scoped bean called UsernamePassword with simple getters and setters like so:

public @RequestScoped class UsernamePassword {

    private String username;

    private String password;

    

    public String getUsername() { return username; }

    public String getPassword() { return password; }

    

    public void setUsername(String username) { this.username = username; }

    public void setPassword(String password) { this.password = password; }

}

And then inject that into the Authenticator bean instead:

public class SimpleAuthenticator extends BaseAuthenticator {


    @Inject UsernamePassword usernamePassword;

    

    // code snipped

}

Of course it is not recommended that you actually do this, however this simplistic example serves adequately for demonstrating the case in point.

The DefaultLoginCredentials bean is provided by PicketLink as a convenience, and is intended to serve as a general purpose Credentials implementation suitable for a variety of use cases. It supports the setting of a userId and credential property, and provides convenience methods for working with text-based passwords. It is a request-scoped bean and is also annotated with @Named so as to make it accessible directly from the view layer.

A view technology with support for EL binding (such as JSF) can access the DefaultLoginCredentials bean directly via its bean name, loginCredentials. The following code snippet shows some JSF markup that binds the controls of a login form to DefaultLoginCredentials:

<div class="loginRow">

  <h:outputLabel for="name" value="Username" styleClass="loginLabel"/>

  <h:inputText id="name" value="#{loginCredentials.userId}"/>

</div>



<div class="loginRow">

  <h:outputLabel for="password" value="Password" styleClass="loginLabel"/>

  <h:inputSecret id="password" value="#{loginCredentials.password}" redisplay="true"/>

</div>

In a Java EE environment PicketLink provides a set of producer methods for injecting the primary identity management objects into your CDI beans. The following table outlines which IDM classes may be injected, and the CDI scope of each of the beans.

Since the IdentityManager and RelationshipManager beans are request scoped beans (as per the above table) it is not possible to inject them directly into a @Startup bean as there is no request scope available at application startup time. Instead, if you wish to use the IDM API within a @Startup bean in your Java EE application you may inject the PartitionManager (which is application-scoped) from which you can then get references to the IdentityManager and RelationshipManager:

@Singleton

@Startup

public class InitializeSecurity {

    @Inject private PartitionManager partitionManager;


    @PostConstruct

    public void create() {

        // Create an IdentityManager

        IdentityManager identityManager = partitionManager.createIdentityManager();


        User user = new User("shane");

        identityManager.add(user);


        Password password = new Password("password");

        identityManager.updateCredential(user, password);

        

        // Create a RelationshipManager

        RelationshipManager relationshipManager = partitionManager.createRelationshipManager();

        

        // Create some relationships

    }

}

Since PicketLink has multiple-partition support, it is important to be able to control the associated partition for the injected IdentityManager. By default, PicketLink will injected an IdentityManager for the default Realm (i.e. the org.picketlink.idm.model.basic.Realm partition with a name of default). If your application has basic security requirements then this might well be adequate, however if you wish to override this default behaviour then simply provide a producer method annotated with the @PicketLink qualifier that returns the default partition for your application:

@ApplicationScoped

public class DefaultPartitionProducer {

    @Inject PartitionManager partitionManager;

    

    @Produces

    @PicketLink

    public Partition getDefaultPartition() {

        return partitionManager.getPartition(Tier.class, "warehouse.dispatch");

    }

}

In the code above we can see that the getter methods of the identity objects are annotated with @AttributeProperty. This annotation (from the org.picketlink.idm.model.annotation package) is used to indicate that the property of the identity object should be persisted by the configured identity store when creating or updating the identity object. If this annotation was missing, then the property value would be null when loading the identity object from the identity store.

In this example, the annotation is placed on the getter method however it is also valid to place it on the corresponding field value.

In the above code listing for the Agent class, we can also see that there is a @Unique annotation on the getLoginName() getter method (in addition to the @AttributeProperty annotation). This special annotation (also from the org.picketlink.idm.model.annotation package) is used to indicate to PicketLink that a unique constraint must be enforced on the property value - i.e. no two Agent objects (or their subclasses) may return the same value for getLoginName().

Creating a custom partition type is extremely simple. PicketLink provides an abstract base class called AbstractPartition (see above) which makes creating a custom partition class a trivial exercise - simply extend the AbstractPartition class and then add any additional property getter/setter methods that you might require. Let's take a look at the built-in Realm class to see how little code it requires to create a custom partition:

@IdentityPartition(supportedTypes = {IdentityType.class})

public class Realm extends AbstractPartition {

    public Realm() {

        super(null);

    }


    public Realm(String name) {

        super(name);

    }

}

The @IdentityPartition annotation must be present on the partition class - the supportedTypes member is used to configure which identity types may be stored in this partition. Any identity object (or subclass) specified by supportedTypes is valid. There is also a unsupportedTypes member which may be used to specify identity types which may not be stored in the partition. This value can be used to trim unsupported classes (and their subclasses) off the supportedTypes.

For IdentityStore implementations that support multiple credential types (such as JPAIdentityStore and FileBasedIdentityStore), the implementation may choose to also implement the CredentialStore interface to simplify the interaction between the CredentialHandler and the IdentityStore. The CredentialStore interface declares methods for storing and retrieving credential values within an identity store, as follows:

public interface CredentialStore {

   void storeCredential(IdentityContext context, Account account,

                        CredentialStorage storage);

   <T extends CredentialStorage> T retrieveCurrentCredential(IdentityContext context,

                                                 Account account, Class<T> storageClass);

   <T extends CredentialStorage> List<T> retrieveCredentials(IdentityContext context,

                                                 Account account, Class<T> storageClass);

}

The CredentialStorage interface is quite simple and only declares two methods, getEffectiveDate() and getExpiryDate():

public interface CredentialStorage {

   @Stored Date getEffectiveDate();

   @Stored Date getExpiryDate();

}

The most important thing to note above is the usage of the @Stored annotation. This annotation is used to mark the properties of the CredentialStorage implementation that should be persisted. The only requirement for any property values that are marked as @Stored is that they are serializable (i.e. they implement the java.io.Serializable interface). The @Stored annotation may be placed on either the getter method or the field variable itself. Here's an example of one of a CredentialStorage implementation that is built into PicketLink - EncodedPasswordStorage is used to store a password hash and salt value:

public class EncodedPasswordStorage implements CredentialStorage {


    private Date effectiveDate;

    private Date expiryDate;

    private String encodedHash;

    private String salt;


    @Override @Stored

    public Date getEffectiveDate() {

        return effectiveDate;

    }


    public void setEffectiveDate(Date effectiveDate) {

        this.effectiveDate = effectiveDate;

    }


    @Override @Stored

    public Date getExpiryDate() {

        return expiryDate;

    }


    public void setExpiryDate(Date expiryDate) {

        this.expiryDate = expiryDate;

    }


    @Stored

    public String getEncodedHash() {

        return encodedHash;

    }


    public void setEncodedHash(String encodedHash) {

        this.encodedHash = encodedHash;

    }


    @Stored

    public String getSalt() {

        return this.salt;

    }


    public void setSalt(String salt) {

        this.salt = salt;

    }


}

This credential handlers supports a username/password based authentication.

Credentials can be updated as follows:

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

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

In order to validate a credential you need to the following code:

UsernamePasswordCredentials credential = new UsernamePasswordCredentials();


Password password = new Password("abcd1234");


credential.setUsername("jsmith");

credential.setPassword(password);


identityManager.validateCredentials(credential);


if (Status.VALID.equals(credential.getStatus()) {

  // successful validation

} else {

  // invalid credential

}

This credential handlers supports a DIGEST based authentication.

Credentials can be updated as follows:

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

Digest digest = new Digest();


digest.setRealm("PicketLink Realm");

digest.setUsername(user.getLoginName());

digest.setPassword("abcd1234");


identityManager.updateCredential(user, digest);

In order to validate a credential you need to the following code:

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


Digest digest = new Digest();


digest.setRealm("PicketLink Realm");

digest.setUsername(user.getLoginName());

digest.setPassword("abcd1234");


digest.setDigest(DigestUtil.calculateA1(user.getLoginName(), digest.getRealm(), digest.getPassword().toCharArray()));


DigestCredentials credential = new DigestCredentials(digestPassword);


identityManager.validateCredentials(credential);


if (Status.VALID.equals(credential.getStatus()) {

// successful validation

} else {

// invalid credential

}

This credential handlers supports a X509 certificates based authentication.

Credentials can be updated as follows:

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


java.security.cert.X509Certificate clientCert = // get user certificate


identityManager.updateCredential(user, clientCert);

In order to validate a credential you need to the following code:

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


java.security.cert.X509Certificate clientCert = // get user certificate

X509CertificateCredentials credential = new X509CertificateCredentials(clientCert);


identityManager.validateCredentials(credential);


if (Status.VALID.equals(credential.getStatus()) {

// successful validation

} else {

// invalid credential

}

In some cases, you just want to trust the provided certificate and only check the existence of the principal:

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


java.security.cert.X509Certificate clientCert = // get user certificate

X509CertificateCredentials credential = new X509CertificateCredentials(clientCert);


// trust the certificate and only check the principal existence

credential.setTrusted(true);


identityManager.validateCredentials(credential);


if (Status.VALID.equals(credential.getStatus()) {

// successful validation

} else {

// invalid credential

}

This credential handlers supports a username/password based authentication.

Credentials can be updated as follows:

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


TOTPCredential credential = new TOTPCredential("abcd1234", "my_totp_secret");


identityManager.updateCredential(user, credential);

Users can have multiple TOTP tokens, one for each device. You can provide configure tokens for a specific user device as follows:

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


TOTPCredential credential = new TOTPCredential("abcd1234", "my_totp_secret");


credential.setDevice("My Cool Android Phone");


identityManager.updateCredential(user, credential);

In order to validate a credential you need to the following code:

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


TOTPCredentials credential = new TOTPCredentials();


credential.setUsername(user.getLoginName());

credential.setPassword(new Password("abcd1234"));


TimeBasedOTP totp = new TimeBasedOTP();


// let's manually generate a token based on the user secret

String token = totp.generate("my_totp_secret");


credential.setToken(token);


// if you want to validate the token for a specific device

// credential.setDevice("My Cool Android Phone");


identityManager.validateCredentials(credential);


if (Status.VALID.equals(credential.getStatus()) {

  // successful validation

} else {

  // invalid credential

}

PicketLink also provides an utility class with some very useful and common methods to manipulate the basic identity model. Along the documentation you'll find a lot of examples using the the following class: org.picketlink.idm.model.basic.BasicModel. If you're using the basic identity model, this helper class can save you a lot of code and make your application even more simple.

The list below summarizes some of the functionalities provided by this class:

One import thing to keep in mind is that the BasicModel helper class is only suitable if you're using the types provided by the basic identity model, only. If you are using custom types, even if those are sub-types of any of the types provided by the basic identity model, you should handle those custom types directly using the PicketLink IDM API.

As an example, let's suppose you have a custom type which extends the Agent type.

  SalesAgent salesAgent = BasicModel.getUser(identityManager, "someSalesAgent");

The code above will never return a SalesAgent instance. The correct way of doing that is using the Query API directly as follows:

  public SaleAgent findSalesAgent(String loginName) {

      List<SaleAgent> result = identityManager

                                .createIdentityQuery(SaleAgent.class)

                                .setParameter(SaleAgent.LOGIN_NAME, loginName)

                                .getResultList();

      return result.isEmpty() ? null : result.get(0);

}

The following code example demonstrates how to create a new user with the following properties:

  User user = new User("jsmith");

  user.setFirstName("John");

  user.setLastName("Smith");

  user.setEmail("jsmith@acme.com");

  identityManager.add(user);

Once the User is created, it's possible to look it up using its login name:

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

User properties can also be modified after the User has already been created. The following example demonstrates how to change the e-mail address of the user we created above:

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

  user.setEmail("john@smith.com");

  identityManager.update(user);

Users may also be deleted. The following example demonstrates how to delete the user previously created:

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

  identityManager.remove("jsmith");

The following example demonstrates how to create a new group called employees:

  Group employees = new Group("employees");

It is also possible to assign a parent group when creating a group. The following example demonstrates how to create a new group called managers, using the employees group created in the previous example as the parent group:

  Group managers = new Group("managers", employees);

To lookup an existing Group, the getGroup() method may be used. If the group name is unique, it can be passed as a single parameter:

  Group employees = BasicModel.getGroup(identityManager, "employees");

If the group name is not unique, the parent group must be passed as the second parameter (although it can still be provided if the group name is unique):

  Group managers = BasicModel.getGroup(identityManager, "managers", employees);

It is also possible to modify a Group's name and other properties (besides its parent) after it has been created. The following example demonstrates how to disable the "employees" group we created above:

  Group employees = BasicModel.getGroup(identityManager, "employees");

  employees.setEnabled(false);

  identityManager.update(employees);

To remove an existing group, we can use the remove() method:

  Group employees = BasicModel.getGroup(identityManager, "employees");

  identityManager.remove(employees);

PicketLink provides a number of built-in relationship types, designed to address the most common requirements of a typical application. The following sections describe the built-in relationships and how they are intended to be used. Every built-in relationship type extends the AbstractAttributedType abstract class, which provides the basic methods for setting a unique identifier value and managing a set of attribute values:

What this means in practical terms, is that every single relationship is assigned and can be identified by, a unique identifier value. Also, arbitrary attribute values may be set for all relationship types, which is useful if you require additional metadata or any other type of information to be stored with a relationship.

Configuration in PicketLink is in essence quite simple; an IdentityConfiguration object must first be created to hold the PicketLink configuration options. Once all configuration options have been set, you just create a PartitionManager instance passing the previously created configuration. The PartitionManager can then be used to create Partition and IdentityManager instances.

The IdentityConfiguration is usually created using a Configuration Builder API, which provides a rich and fluent API for every single aspect of PicketLink configuration.

If you'd like to get up and running with IDM quickly, the good news is that PicketLink will provide a default configuration that stores your identity data on the file system if no other configuration is available. This means that if you have the PicketLink libraries in your project, you can simply inject the PartitionManager, IdentityManager or RelationshipManager beans into your own application and start using them immediately:

@Inject PartitionManager partitionManager;

@Inject IdentityManager identityManager;

@Inject RelationshipManager relationshipManager;

In certain cases the default configuration may not be enough to your application. You can easily provide your own configuration by observing a specific IdentityConfigurationEvent:

@ApplicationScoped

public static class PicketLinkConfiguration {


  public void observeIdentityConfigurationEvent(@Observes IdentityConfigurationEvent event) {

    IdentityConfigurationBuilder builder = event.getConfig();


    // use the builder to provide your own configuration

  }

}

You can also provide your own configuration by producing one or more IdentityConfiguration instances using a @Producer annotated method:

@ApplicationScoped

public static class PicketLinkConfiguration {


  @Produces

  public IdentityConfiguration produceJPAConfiguration() {

      IdentityConfigurationBuilder builder = new IdentityConfigurationBuilder();


      builder

          .named("jpa.config")

              .stores()

                  .jpa()

                    // configure the JPA store


      return builder.build();

  }


  @Produces

  public IdentityConfiguration produceLDAPConfiguration() {

      IdentityConfigurationBuilder builder = new IdentityConfigurationBuilder();


      builder

          .named("ldap.config")

              .stores()

                  .ldap()

                      // configure the LDAP store


      return builder.build();

  }

}