10.3. ACL Permissions

Prev
PicketLink Reference Documentation
Next

⁠10.3. ACL Permissions

An ACL (Access Control List) can be used to control which identities may invoke specific operations on application resources. Underneath the covers, ACL security checks are handled by the PersistentPermissionResolver, which reads the ACL entries for each resource via the PermissionStore, which is typically a wrapper around some form of persistent storage such as database table.

Report a bug

⁠10.3.1. The PermissionManager Bean

ACL permissions are managed via the PermissionManager. Actually, this bean is used by the Identity when you invoke its hasPermission methods. An instance of this bean can be obtained by injecting the PermissionManager as follows:

@Inject PermissionManager permissionManager;

Note

The PermissionManager bean is injected based on the current partition defined by the application. If no partition was specified, the bean is injected based on the default partition.

You can also obtain a reference to the PermissionManager from a PartitionManager via the createPermissionManager() method:

@Inject PartitionManager partitionManager;
        
public void managePermissions() {
    PermissionManager permissionManager = partitionManager.createPermissionManager();
}

In the example above, the PermissionManager is being created based on the default partition. But you may also specify a partition when creating it:

@Inject PartitionManager partitionManager;
        
public void managePermissions() {
    Realm partition = partitionManager.getPartition(Realm.class, "MyPartition");
    PermissionManager permissionManager = partitionManager.createPermissionManager(partition);
}

Once you have a reference to the PermissionManager, you can use it to grant permissions:

public void allowRead(User user, Customer customer) {
    permissionManager.grantPermission(user, customer, "READ");
}

The grantPermission() method accepts three parameters:

void grantPermission(IdentityType assignee, Object resource, String operation);

The assignee is the identity to which you wish to grant the permission. The resource is the application resource for which the permission applies. The operation is a String value representing the action that the assignee may invoke in relation to the resource.

Resources may conceivably be any type of Object so long as there exists a unique, serializable value that can be determined or in some way calculated from the resource object, which uniquely identifies that resource from other resources of the same type. This unique value is called the identifier, an example of which might be the primary key value of an entity bean. The PermissionHandler SPI (see section below) is responsible for generating identifier values for resource objects.

The revokePermission() method is used to remove permissions. Like grantPermission(), it also accepts three parameters:

void revokePermission(IdentityType assignee, Object resource, String operation);

It is also possible to revoke all assigned permissions for a single resource via the clearPermissions() method. This is useful for example if you wish to delete the resource and don't wish to leave orphaned permissions:

void clearPermissions(Object resource);

There are also a number of overloaded methods available for querying permissions. These methods take an assortment of parameters depending on exactly which permissions you wish to find:

List<Permission> listPermissions(Object resource);

List<Permission> listPermissions(Class<?> resourceClass, Serializable identifier);

List<Permission> listPermissions(Object resource, String operation);

List<Permission> listPermissions(Class<?> resourceClass, Serializable identifier, 
                                 String operation);

Here's some examples:

// List all permissions for a known Product
Product p = lookupProduct("grapes");
List<Permission> permissions = permissionManager.listPermissions(p);

// List all permissions for a Product where we know the resource class 
// and the identifier
List<Permission> permissions = permissionManager.listPermissions(
    Product.class, "bananas");

// List all "DELETE" permissions that have been granted for a Product
Product p = lookupProduct("apples");
List<Permissions> permissions = permissionManager.listPermissions(p, "DELETE");

// List all "UPDATE" permissions for a Product where we know the 
// resource class and the identifier
List<Permissions> permissions = permissionManager.listPermissions(
    Product.class, "oranges", "UPDATE");

Report a bug