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