Application roles are represented by the Grant relationship, which is used to assign application-wide privileges to a User or Agent.

The IdentityManager interface provides methods for directly granting a role. Here's a simple example:

  User bob = BasicModel.getUser(identityManager, "bob");

  Role superuser = BasicModel.getRole(identityManager, "superuser");

  BasicModel.grantRole(relationshipManager, bob, superuser);

The above code is equivalent to the following:

  User bob = BasicModel.getUser(identityManager, "bob");

  Role superuser = BasicModel.getRole(identityManager, "superuser");

  Grant grant = new Grant(bob, superuser);

  identityManager.add(grant);

A granted role can also be revoked using the revokeRole() method:

  User bob = BasicModel.getUser(identityManager, "bob");

  Role superuser = BasicModel.getRole(identityManager, "superuser");

  BasicModel.revokeRole(relationshipManager, bob, superuser);

To check whether an identity has a specific role granted to them, we can use the hasRole() method:

  User bob = BasicModel.getUser(identityManager, "bob");

  Role superuser = BasicModel.getRole(identityManager, "superuser");

  boolean isBobASuperUser = BasicModel.hasRole(relationshipManager, bob, superuser);

The GroupMembership and GroupRole relationships are used to represent a user's membership within a Group, and a user's role for a group, respectively.

A Group is typically used to form logical collections of users. Within an organisation, groups are often used to mirror the organisation's structure. For example, a corporate structure might consist of a sales department, administration, management, etc. This structure can be modelled in PicketLink by creating corresponding groups such as sales, administration, and so forth. Users (who would represent the employees in a corporate structure) may then be assigned group memberships corresponding to their place within the company's organisational structure. For example, an employee who works in the sales department may be assigned to the sales group. Specific application privileges can then be blanket assigned to the sales group, and anyone who is a member of the group is free to access the application's features that require those privileges.

The GroupRole relationship type should be used when it is intended for an identity to perform a specific role for a group, but not be an actual member of the group itself. For example, an administrator of a group of doctors may not be a doctor themselves, but have an administrative role to perform for that group. If the intent is for an individual identity to both be a member of a group and have an assigned role in that group also, then the identity should have both GroupRole and GroupMembership relationships for that group.

Let's start by looking at a simple example - we'll begin by making the assumption that our organization is structured in the following way:

The following code demonstrates how we would create the hypothetical Sales group which is displayed at the head of the above organisational chart:

  Group sales = new Group("Sales");

  identityManager.add(sales);

We can then proceed to create its subgroups:

identityManager.add(new Group("North America", sales);

identityManager.add(new Group("EMEA", sales);

identityManager.add(new Group("Asia", sales);

// and so forth

The second parameter of the Group() constructor is used to specify the group's parent group. This allows us to create a hierarchical group structure, which can be used to mirror either a simple or complex personnel structure of an organisation. Let's now take a look at how we assign users to these groups.

The following code demonstrates how to assign an administrator group role for the Northeast sales group to user jsmith. The administrator group role may be used to grant certain users the privilege to modify permissions and roles for that group:

Role admin = BasicModel.getRole(identityManager, "administrator");

User user = BasicModel.getUser(identityManager, "jsmith");

Group group = BasicModel.getGroup(identityManager, "Northeast");

BasicModel.grantGroupRole(relationshipManager, user, admin, group);

A group role can be revoked using the revokeGroupRole() method:

BasicModel.revokeGroupRole(relationshipManager, user, admin, group);

To test whether a user has a particular group role, you can use the hasGroupRole() method:

boolean isUserAGroupAdmin = BasicModel.hasGroupRole(relationshipManager, user, admin, group);

Next, let's look at some examples of how to work with simple group memberships. The following code demonstrates how we assign sales staff rbrown to the Northeast sales group:

User user = BasicModel.getUser(identityManager, "rbrown");

Group group = BasicModel.getGroup(identityManager, "Northeast");

BasicModel.addToGroup(relationshipManager, user, group);

A User may also be a member of more than one Group; there are no built-in limitations on the number of groups that a User may be a member of.

We can use the removeFromGroup() method to remove the same user from the group:

BasicModel.removeFromGroup(relationshipManager, user, group);

To check whether a user is the member of a group we can use the isMember() method:

boolean isUserAMember = BasicModel.isMember(relationshipManager, user, group);

Relationships can also be created via the add() method. The following code is equivalent to assigning a group role via the grantGroupRole() method shown above:

Role admin = BasicModel.getRole(identityManager, "administrator");

User user = BasicModel.getUser(identityManager, "jsmith");

Group group = BasicModel.getGroup(identityManager, "Northeast");

GroupRole groupRole = new GroupRole(user, group, admin);

identityManager.add(groupRole);