Chapter 7. Identity Management

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.

7.1.1. Recommended Database Schema

The following schema diagram is an example of a suitable database structure for storing IDM-related data:

Please note that the data types shown in the above diagram might not be available in your RDBMS; if that is the case please adjust the data types to suit.

7.1.2. Default Database Schema

If you do not wish to provide your own JPA entities for storing IDM-related state, you may use the default schema provided by PicketLink in the picketlink-idm-schema module. This module contains a collection of entity beans suitable for use with JPAIdentityStore. To use this module, add the following dependency to your Maven project's pom.xml file:


<dependency>

    <groupId>org.picketlink</groupId>

    <artifactId>picketlink-idm-schema</artifactId>

    <version>${picketlink.version}</version>

</dependency>

In addition to including the above dependency, the default schema entity beans must be configured in your application's persistence.xml file. Add the following entries within the persistence-unit section:


<class>org.picketlink.idm.jpa.schema.IdentityObject</class>

<class>org.picketlink.idm.jpa.schema.PartitionObject</class>

<class>org.picketlink.idm.jpa.schema.RelationshipObject</class>

<class>org.picketlink.idm.jpa.schema.RelationshipIdentityObject</class>

<class>org.picketlink.idm.jpa.schema.RelationshipObjectAttribute</class>

<class>org.picketlink.idm.jpa.schema.IdentityObjectAttribute</class>

<class>org.picketlink.idm.jpa.schema.CredentialObject</class>

<class>org.picketlink.idm.jpa.schema.CredentialObjectAttribute</class>

7.1.3. Configuring an EntityManager

Before the JPA identity store can be used, it must be provided with an EntityManager so that it can connect to a database. In Java EE this can be done by providing a producer method within your application that specifies the @org.picketlink.annotations.PicketLink qualifier, for example like so:

@Produces

@PicketLink

@PersistenceContext(unitName = "picketlink")

private EntityManager picketLinkEntityManager;

7.1.4. Configuring the Identity class

The Identity class is the entity bean that is used to store the record for users, roles and groups. It should be annotated with @IdentityType and declare the following field values:

Table 7.1. Identity class fields

Property	Annotation	Description
ID	`@Identifier`	The unique identifier value for the identity (can also double as the primary key value)
Discriminator	`@Discriminator`	Indicates the identity type (i.e. user, agent, group or role) of the identity.
Partition	`@IdentityPartition`	The partition (realm or tier) that the identity belongs to
Login name	`@LoginName`	The login name for agent and user identities (for other identity types this will be null)
Name	`@IdentityName`	The name for group and role identities (for other identity types this will be null)
First Name	`@FirstName`	The first name of a user identity
Last Name	`@LastName`	The last name of a user identity
E-mail	`@Email`	The primary e-mail address of a user identity
Enabled	`@Enabled`	Indicates whether the identity is enabled
Creation date	`@CreationDate`	The creation date of the identity
Expiry date	`@ExpiryDate`	The expiry date of the identity
Group parent	`@Parent`	The parent group (only used for Group identity types, for other types will be null)
Group path	`@GroupPath`	Represents the full group path (for Group identity types only)

The following code shows an example of an entity class configured to store Identity instances:

Example 7.1. Example Identity class

@IdentityType

@Entity

public class IdentityObject implements Serializable {

    

    @Discriminator

    private String discriminator;


    @ManyToOne

    @IdentityPartition

    private PartitionObject partition;


    @Identifier

    @Id

    private String id;


    @LoginName

    private String loginName;


    @IdentityName

    private String name;


    @FirstName

    private String firstName;


    @LastName

    private String lastName;


    @Email

    private String email;


    @Enabled

    private boolean enabled;


    @CreationDate

    @Temporal(TemporalType.TIMESTAMP)

    private Date creationDate;


    @ExpiryDate

    @Temporal(TemporalType.TIMESTAMP)

    private Date expiryDate;


    @ManyToOne

    @Parent

    private IdentityObject parent;


    @GroupPath

    private String groupPath;              

    

    // getters and setters

}

7.1.5. Configuring the Attribute class

The Attribute class is used to store Identity attributes, and should be annotated with @IdentityAttribute

Table 7.2. Attribute class fields

Property	Annotation	Description
Identity	`@Parent`	The parent identity object to which the attribute value belongs
Name	`@AttributeName`	The name of the attribute
Value	`@AttributeValue`	The value of the attribute
Type	`@AttributeType`	The fully qualified classname of the attribute value class

Example 7.2. Example Attribute class

@Entity

@IdentityAttribute

public class IdentityAttribute implements Serializable {

    @Id @GeneratedValue private Long id;


    @ManyToOne @JoinColumn

    @Parent

    private IdentityObject identityObject;


    @AttributeName

    private String name;                


    @AttributeValue

    private String value;


    @AttributeType

    private String type;

    

    // getters and setters

}

7.1.6. Configuring the Credential class

The credential entity is used to store user credentials such as passwords and certificates, and should be annotated with @IdentityCredential.

Table 7.3. Credential class fields

Property	Annotation	Description
Type	`@CredentialType`	The fully qualified classname of the credential type
Value	`@CredentialValue`	The value of the credential
Effective Date	`@EffectiveDate`	The effective date of the credential
Expiry Date	`@ExpiryDate`	The expiry date of the credential
Identity	`@Parent`	The parent identity to which the credential belongs

Example 7.3. Example Credential class

@Entity

@IdentityCredential

public class IdentityCredential implements Serializable {

    @Id @GeneratedValue private Long id;


    @CredentialType

    private String type;


    @CredentialValue

    private String credential;


    @EffectiveDate

    @Temporal (TemporalType.TIMESTAMP)

    private Date effectiveDate;


    @ExpiryDate

    @Temporal (TemporalType.TIMESTAMP)

    private Date expiryDate;


    @Parent

    @ManyToOne

    private IdentityObject identityType;

    

    // getters and setters

}

7.1.7. Configuring the Credential Attribute class

The Credential Attribute class is used to store arbitrary attribute values relating to the credential. It should be annotated with @CredentialAttribute.

Table 7.4. Credential Attribute class fields

Property	Annotation	Description
Credential Object	`@Parent`	The parent credential to which this attribute belongs
Attribute Name	`@AttributeName`	The name of the attribute
Attribute Value	`@AttributeValue`	The value of the attribute

Example 7.4. Example Credential Attribute class

@Entity

@CredentialAttribute

public class IdentityCredentialAttribute implements Serializable {

    @Id @GeneratedValue private Long id;


    @ManyToOne @JoinColumn

    @Parent

    private IdentityCredential credential;


    @AttributeName

    private String name;


    @AttributeValue

    private String value;

    

    // getters and setters

}

7.1.8. Configuring the Relationship class

Relationships are used to define typed associations between two or more identities. The Relationship class should be annotated with @Relationship.

Table 7.5. Relationship class fields

Property	Annotation	Description
Identifier	`@Identifier`	Unique identifier that represents the specific relationship (can also double as the primary key)
Relationship Class	`@RelationshipClass`	The fully qualified class name of the relationship type

Example 7.5. Example Relationship class

@Relationship

@Entity

public class Relationship implements Serializable {

    @Id 

    @Identifier

    private String id;


    @RelationshipClass

    private String type;


    // getters and setters

}

7.1.9. Configuring the Relationship Identity class

The Relationship Identity class is used to store the specific identities that participate in a relationship. It should be annotated with @RelationshipIdentity.

Table 7.6. Relationship Identity class fields

Property	Annotation	Description
Relationship Descriptor	`@Discriminator`	Denotes the role of the identity in the relationship
Relationship Identity	`@Identity`	The identity that is participating in the relationship
Relationship	`@Parent`	The parent relationship object to which the relationship identity belongs

Example 7.6. Example Relationship Identity class

@RelationshipIdentity

@Entity

public class RelationshipIdentityObject implements Serializable {

    @Id @GeneratedValue private Long id;


    @Discriminator

    private String descriptor;


    @RelationshipIdentity

    @ManyToOne

    private IdentityObject identityObject;


    @Parent

    @ManyToOne

    private RelationshipObject relationshipObject;

    

    // getters and setters

}

7.1.10. Configuring the Relationship Attribute class

The Relationship Attribute class is used to store arbitrary attribute values that relate to a specific relationship. It should be annotated with @RelationshipAttribute.

Table 7.7. Relationship Attribute class fields

Property	Annotation	Description
Relationship	`@Parent`	The parent relationship object to which the attribute belongs
Attribute Name	`@AttributeName`	The name of the attribute
Attribute value	`@AttributeValue`	The value of the attribute

Example 7.7. Example Relationship Attribute class

@Entity

@RelationshipAttribute

public class RelationshipObjectAttribute implements Serializable {

    @Id @GeneratedValue private Long id;


    @ManyToOne @JoinColumn

    @Parent

    private Relationship relationship;


    @AttributeName

    private String name;


    @RelationshipValue

    private String value;

    

    // getters and setters

}

7.1.11. Configuring the Partition class

The Partition class is used to store information about partitions, i.e. Realms and Tiers. It should be annotated with @Partition.

Table 7.8. Partition class fields

Property	Annotation	Description
ID	`@Identifier`	The unique identifier value for the partition
Type	`@Discriminator`	The type of partition, either Realm or Tier
Parent	`@Parent`	The parent partition (only used for Tiers)

Example 7.8. Example Partition class

@Entity

@Partition

public class PartitionObject implements Serializable {

    @Id @Identifier

    private String id;


    @Discriminator

    private String type;


    @ManyToOne 

    @Parent

    private PartitionObject parent;

    

    // getters and setters

}

7.1.12. Providing a `EntityManager`

Sometimes you may need to configure how the EntityManager is provided to the JPAIdentityStore, like when your application is using CDI and you must run the operations in the scope of the current transaction by using a injected EntityManager instance.

In cases like that, you need to initialize the SecurityContext by providing a ContextInitializer implementation, as discussed in Security Context Configuration. The JPAContextInitializer is provided by PicketLink and can be used to initialize the security context with a specific EntityManager instance. You can always extend this class and provide your own way to obtain the EntityManager from your application's environment.

IdentityConfigurationBuilder builder = new IdentityConfigurationBuilder();


builder

  .stores()

    .file()

      .addContextInitializer(new JPAContextInitializer(emf) {

        @Override

        public EntityManager getEntityManager() {

          // logic goes here

        }

      });

}

By default, the JPAContextInitializer creates a EntityManager from the EntityManagerFacatory provided when creating a new instance.