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.

Actually it's possible to configure IDM with XML configuration. This possibility is good especially in case when you want Picketlink IDM to be part of bigger system and your users won't have a possibility to change source code and so they can't configure it programmatically with the Builder API. So they will just need to change the configuration in XML file instead of doing some changes directly in source code.