PicketLink Reference Documentation

The base module provides the integration framework required to use PicketLink within a Java EE application. It defines a flexible authentication API that allows pluggable authentication mechanisms to be easy configured, with a sensible default authentication policy that delegates to the identity management subsystem. It provides session-scoped authentication tracking for web applications and other session-capable clients, plus a customisable permissions SPI that supports a flexible range of authorization mechanisms for object-level security. It is also the "glue" that integrates all of the PicketLink modules together to provide a cohesive API.

The base module libraries are as follows:

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);

            setUser(new SimpleUser("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 getAgent() methods (while also providing matching setStatus() and setAgent() 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 setUser() method is used to set the user (in this case by creating a new instance of SimpleUser). 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>

The following diagram shows the main components that realize PicketLink Identity Management:

For most use cases, users will only work with the IdentityManagerFactory and IdentityManager classes. Only advanced use cases may require a deep knowledge about other components in order to customize the default behaviour/implementation to suit a specific requirement.

The diagram below shows an overview about how a specific identity management operation is realized:

PicketLink IDM design is quite flexible and allows you to configure or even customize most of the behaviours described above. As stated earlier, most use cases require minimal knowledge about these details and the default implementation should be enough to satisfy the majority of requirements.

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 IdentityManagerFactory instance passing the previously created configuration. The IdentityManagerFactory can then be used to create IdentityManager instances via the createIdentityManager() method.

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

Each IdentityManager instance has its own security context, represented by the SecurityContext class. The security context contains temporary state which is maintained for one or more identity management operations within the scope of a single realm or tier. The IdentityManager (and its associated SecurityContext) is typically modelled as a request-scoped object (for environments which support such a paradigm, such as a servlet container), or alternatively as an actor within the scope of a transaction. In the latter case, the underlying resources being utilised by the configured identity stores (such as a JPA EntityManager) would participate in the active transaction, and changes made as a result of any identity management operations would either be committed or rolled back as appropriate for the logic of the encapsulating business method.

The following sections describe various ways that configuration may be performed in different environments.

Configuration for Identity Management can be defined programmatically using the Configuration Builder API. The aim of this API is to make it easier to chain coding of configuration options in order to speed up the coding itself and make the configuration more readable.

Let's assume that you want to quick start with PicketLink Identity Management features using a file-based Identity Store. First, a fresh instance of IdentityConfiguration is created using the IdentityConfigurationBuilder helper object, where we choose which identity store we want to use (in this case a file-based store) and any other configuration option, if necessary. Finally, we use the configuration to create a IdentityManagerFactory from where we can create IdentityManager instances and start to perform Identity Management operations:

IdentityConfigurationBuilder builder = new IdentityConfigurationBuilder();

        

builder

  .stores()

  .file()

  .supportAllFeatures();


IdentityConfiguration configuration = builder.build();


IdentityManagerFactory identityManagerFactory = new IdentityManagerFactory(configuration);


IdentityManager identityManager = identityManagerFactory.createIdentityManager();


User user = new SimpleUser("john");


identityManager.add(user);

When configuring identity stores you must tell which features and operations should be executed by them. Features and operations are a key concept if you want to mix stores in order to execute operations against different repositories.

PicketLink provides a Java enum, called FeatureGroup, in which are defined all supported features. The table bellow summarize them:

The features are a determinant factor when choosing an identity store to execute a specific operation. For example, if an identity store is configured with FeatureGroup.user we're saying that all User operations should be executed by this identity store. The same goes for FeatureGroup.credential, we're just saying that credentials can also be updated and validated using the identity store.

Beside that, provide only the feature is not enough. We must also tell the identity store which operations are supported by a feature. For example, we can configure a identity store to support only read operations for users, which is very common when using the LDAP identity store against a read-only tree. Operations are also defined by an enum, called FeatureOperation, as follows:

During the configuration you can provide which features and operations should be supported using the Configuration API. You don't need to be forced to specify them individually, if you want to support all features and operations for a particular identity store you can use:

IdentityConfigurationBuilder builder = new IdentityConfigurationBuilder();


builder

  .stores()

    .file()

      .supportAllFeatures();  

}

For a more granular configuration you can also use:

IdentityConfigurationBuilder builder = new IdentityConfigurationBuilder();


builder

  .stores()

    .file()

      .supportFeature(

        FeatureGroup.agent, 

        FeatureGroup.user, 

        FeatureGroup.role, 

        FeatureGroup.group)  

}

The configuration above defines the features individually. In this case the configured features are also supporting all operations. If you want to specify which operation should be supported by a feature you can use:

IdentityConfigurationBuilder builder = new IdentityConfigurationBuilder();


builder

  .stores()

    .file()

      .supportFeature(FeatureGroup.agent, FeatureOperation.read)

      .supportFeature(FeatureGroup.user, FeatureOperation.read))

      .supportFeature(FeatureGroup.role, FeatureOperation.create))

      .supportFeature(FeatureGroup.role, FeatureOperation.read))

      .supportFeature(FeatureGroup.role, FeatureOperation.update))

      .supportFeature(FeatureGroup.role, FeatureOperation.delete))  

      .supportFeature(FeatureGroup.group, FeatureOperation.create))

      .supportFeature(FeatureGroup.group, FeatureOperation.read))

      .supportFeature(FeatureGroup.group, FeatureOperation.update))

      .supportFeature(FeatureGroup.group, FeatureOperation.delete))  

}

For a more complex configuration evolving multiple identity stores with a different feature set, look at the example bellow:

IdentityConfigurationBuilder builder = new IdentityConfigurationBuilder();


builder

  .stores()

    .ldap()

      .supportFeature(FeatureGroup.agent)

      .supportFeature(FeatureGroup.user)

      .supportFeature(FeatureGroup.credential)

    .jpa()

      .supportFeature(FeatureGroup.role)

      .supportFeature(FeatureGroup.group)

      .supportFeature(FeatureGroup.relationship)

}

The configuration above shows how to use LDAP to store only agents, users and credentials and database for roles, groups and relationships.

For each of the built-in IdentityStore implementations there is a corresponding IdentityStoreConfiguration implementation - the following sections describe each of these in more detail.

The JPA identity store uses a relational database to store identity state. The configuration for this identity store provides control over which entity beans are used to store identity data, and how their fields should be used to store various identity-related state. The entity beans that store the identity data must be configured using the annotations found in the org.picketlink.jpa.annotations package. All identity configuration annotations listed in the tables below are from this package.

The LDAP identity store allows an LDAP directory server to be used to provide identity state. You can use this store in read-only or write-read mode, depending on your permissions on the server.

This identity store uses the file system to persist identity state. The configuration for this identity store provides control over where to store identity data and if the state should be preserved between initializatons.

Identity data is stored using the Java Serialization API.

TODO

In a Java EE environment, PicketLink provides a producer method for IdentityManager, so getting a reference to it is as simply as injecting it into your beans:

@Inject IdentityManager identityManager;

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

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

  identityManager.remove("jsmith");

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

  Group employees = new SimpleGroup("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 SimpleGroup("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 = identityManager.getGroup("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 = identityManager.getGroup("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 = identityManager.getGroup("employees");

  employees.setEnabled(false);

  identityManager.update(employees);

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

  Group employees = identityManager.getGroup("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.

One of the strengths of PicketLink is its ability to support custom relationship types. This extensibility allows you, the developer to create specific relationship types between two or more identities to address the domain-specific requirements of your own application.

To create a custom relationship type, we start by creating a new class that implements the Relationship interface. To save time, we also extend the AbstractAttributedType abstract class which takes care of the identifier and attribute management methods for us:

  public class Authorization extends AbstractAttributedType implements Relationship {

        

  }

The next step is to define which identities participate in the relationship. Once we create our identity property methods, we also need to annotate them with the org.picketlink.idm.model.annotation.RelationshipIdentity annotation. This is done by creating a property for each identity type.

  private User user;

  private Agent application;

  

  @RelationshipIdentity

  public User getUser() {

    return user;

  }

  

  public void setUser(User user) {

    this.user = user;

  }

  

  @RelationshipIdentity

  public Agent getApplication() {

    return application;

  }

  

  public void setApplication(Agent application) {

    this.application = application;

  }

  private String accessToken;

  

  @RelationshipAttribute

  public String getAccessToken() {

    return accessToken;

  }

  

  public void setAccessToken(String accessToken) {

    this.accessToken = accessToken;

  }

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(SecurityContext context, Agent agent, 

                        CredentialStorage storage);

   <T extends CredentialStorage> T retrieveCurrentCredential(SecurityContext context, 

                                                 Agent agent, Class<T> storageClass);

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

                                                 Agent agent, 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;

    }


}

PicketLink has been designed from the ground up to support a system of partitioning, allowing the users, groups and roles of an application to be divided into Realms and Tiers.

A Realm is used to define a discrete set of users, groups and roles. A typical use case for realms is the segregation of corporate user accounts within a multi-tenant application, although it is not limited this use case only. As all identity management operations must be performed within the context of an active partition, PicketLink defines the concept of a default realm which becomes the active partition if no other partition has been specified.

A Tier is a more restrictive type of partition than a realm, as it only allows groups and roles to be defined (but not users). A Tier may be used to define a set of application-specific groups and roles, which may then be assigned to groups within the same Tier, or to users and groups within a separate Realm.

In terms of API, both the Realm and Tier classes implement the Partition interface, as shown in the following class diagram:

Selecting the specific partition that the identity management operations are performed in is controlled by specifying the partition when creating the IdentityManager via the IdentityManagerFactory's overloaded createIdentityManager() methods:

  IdentityManager createIdentityManager();

    IdentityManager createIdentityManager(Partition partition);

The first method (without parameters) will create an IdentityManager instance for the default realm. The second parameter allows a Partition object to be specified. Once the IdentityManager has been created, any identity management methods invoked on it will be performed within the selected partition. To look up the partition object, the IdentityManagerFactory provides two additional methods:

  Realm getRealm(String id);

    Tier getTier(String id);

Here's an example demonstrating how a new user called "bob" is created in a realm called acme:

  Realm acme = identityManagerFactory.getRealm("acme");

    IdentityManager im = identityManagerFactory.createIdentityManager(acme);

    im.add(new SimpleUser("bob"));

The SAML v2 specification defines the concept of SAML protocol bindings (or just bindings). These bindings defines how SAML request-response messages are exchanged onto standard messaging or communication protocols. Currently, PicketLink support the following bindings: