JBoss.orgCommunity Documentation
EntityManager
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.
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-simple-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-simple-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.model.sample.simple.AttributedTypeEntity</class>yes
<class>org.picketlink.idm.jpa.model.sample.simple.AccountTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.RoleTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.GroupTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.IdentityTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.RelationshipTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.RelationshipIdentityTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.PartitionTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.PasswordCredentialTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.DigestCredentialTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.X509CredentialTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.OTPCredentialTypeEntity</class>
<class>org.picketlink.idm.jpa.model.sample.simple.AttributeTypeEntity</class>
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;
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 |
@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;
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
}
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
}
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
}
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
}
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
}
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
}
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
}
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
}
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.