JBoss.orgCommunity Documentation
Table of Contents
PicketLink IDM classifies attributes in two main categories: formal and ad-hoc attributes.
Usually all attributes you need for a specific type is mapped to its properties. We call those attributes formal attributes.. Formal attributes are properties managed by PicketLink and defined directly in your types. By managed, we mean that PicketLink knows how to get the value to store from a specific property and also retrieve its value from the store and populate back to an instance of your type.
But sometimes you may need to define attributes that are not mapped to a specific property of your type. Specially if those are dynamic attributes, whose existence depends on a specific context or rule. We call those attributes ad-hoc attributes. Ad-hoc attributes are not strong-typed as formal attributes, they are just a key/value pair. Where the key is the attribute's name and the latter its value.
Usually all attributes are formal attributes, in the sense that properties of a type are managed by PicketLink. In
order to get them managed by PicketLink you need to annotate each property of your type with Section 3.4.1, “The @AttributeProperty Annotation”
If you take the User type as an example, you'll see that all its properties are defined as follows:
public class User extends Agent {
@AttributeProperty
private String firstName;
@AttributeProperty
private String lastName;
@AttributeProperty
private String email;
}
Formal attributes are strongly-typed as they are directly defined as properties in your type.
Those attributes are also queriable. Which means you can use the Query API to search for types with a specific
property and value. If a property is queriable, we recommend to always create a QueryParameter constant as follows:
public class User extends Agent {
/**
* A query parameter used to set the firstName value.
*/
public static final QueryParameter FIRST_NAME = QUERY_ATTRIBUTE.byName("firstName");
/**
* A query parameter used to set the lastName value.
*/
public static final QueryParameter LAST_NAME = QUERY_ATTRIBUTE.byName("lastName");
/**
* A query parameter used to set the email value.
*/
public static final QueryParameter EMAIL = QUERY_ATTRIBUTE.byName("email");
@AttributeProperty
private String firstName;
@AttributeProperty
private String lastName;
@AttributeProperty
private String email;
}
Once the query parameters are defined and mapped to your properties, you can search for types based on its properties as follows:
IdentityQuery<User> query = identityManager.<User> createIdentityQuery(User.class);
query.setParameter(User.FIRST_NAME, "John");
// find only by the first name
List<User> result = query.getResultList();
for (User user : result) {
// do something
}
The best way to understand ad-hoc attributes is look how they're defined. The example below uses three attributes to define some security questions for an user.
User user = new User("john");
user.setAttribute(new Attribute<Integer>("QuestionTotal", 2);
// attribute for question #1
user.setAttribute(new Attribute<String>("Question1", "What is favorite toy?"));
user.setAttribute(new Attribute<String>("Question1Answer", "Gum"));
// attribute for question #2
user.setAttribute(new Attribute<String>("Question2", "What is favorite word?"));
user.setAttribute(new Attribute<String>("Question2Answer", "Hi"));
identityManager.add(user);
Ad-hoc attributes are not strong-typed as formal attributes, they are just a key/value pair. Where the key is the attribute's name and the latter its value. The key point here is that they offer great flexibility to your identity model as you can define any attribute you want without changing any type.
Note that ad-hoc attributes are not typed. You should use them wisely, otherwise they may become unmanageable.
In theory, all PicketLink types such as IdentityType, Relationship and Partition
support ad-hoc attributes. The reason is that all those types are a subtypes of AttributedType. But in practice,
even if a type support ad-hoc attributes the underlying store may not. Which means you can not use those attributes.
The LDAP Identity Store, for example, does not support ad-hoc attributes at all if used alone. Take a look
at Chapter 9, Identity Management - Working with LDAP for more details about how to support ad-hoc attributes when using the LDAP store.
Those attributes are also queriable. The example below shows how you can use the Query API to search for types using ad-hoc attributes:
IdentityQuery<User> query = identityManager.<User> createIdentityQuery(User.class);
query.setParameter(IdentityType.QUERY_ATTRIBUTE.byName("SomeAttribute"), "SomeAttributeValue");
List<User> result = query.getResultList();
for (User user : result) {
// do something
}