Package com.pushtechnology.diffusion.client.features.control.clients

Interface SecurityControl

All Superinterfaces:
Feature, SecurityStoreFeature
public interface SecurityControl extends SecurityStoreFeature
This feature allows a client session to query and update the security store. The security store is a persistent database maintained by the server containing authorisation rules that control what sessions can do.

Access rights to read and write data and to perform actions on the server are controlled by a fixed set of permissions. When a session is opened, the server assigns it a set of roles based on the principal used to authenticate. The rules in the security store assign each role to a set of permissions. Each role can be assigned zero, one, or many permissions. The same permission can be assigned to multiple roles. Roles can also include other roles to form a role hierarchy, and so inherit permissions from the other roles. Roles are defined implicitly by specifying them in permission assignments or inclusion relationships; there is no need to explicitly create roles in the security store.

Permissions either have 'path' or 'global' scope. Global permissions apply to actions that are server-wide and not specific to a particular path. Path permissions apply to hierarchical context, such as a branch of the topic tree or a branch of the message path hierarchy.

Evaluation of global permissions

A session has a global permission if any of its roles are assigned the permission.

Evaluation of path permissions

A session has a permission for a path if any of its roles have the permission for the path.

Path permissions can be assigned to a role for a path. The permissions are inherited by all descendant paths for the role, except paths that have a separate permission assignment for the role or that are isolated and their descendant paths.

Default path permissions can be assigned to a role to set permissions at the root of the path hierarchy. A default permission assignment applies to all paths without direct or inherited path permission assignments, except paths that are isolated and their descendant paths.

The permissions a session has for a path are determined as follows:

  1. If the path has permission assignments for one or more of the sessions roles, the applicable permissions are the union of all of the assigned permissions.
  2. Otherwise, if the path is not isolated, and its parent path has permission assignments for one or more of the sessions roles, the applicable permissions are the union of all of the permissions assigned to the parent path. This rule is applied recursively, for each remaining parent path.
  3. Otherwise, if the neither the path nor any of its parent paths have permission assignments for one of the sessions role or are isolated, the applicable permissions are the union of the default permissions assigned to each role.
  4. If no applicable permissions are found, the session has no permissions for that path.

Path permission evaluation prior to Diffusion 6.5

The way path permissions are evaluated changed in Diffusion 6.5. In previous releases, permissions assigned to a path for a role blocked the inheritance of path permissions assigned to other roles. This made it hard to compose authorisation polices for differing roles.

The path permissions model was changed in Diffusion 6.5 so the set of permissions granted to a session for a path is formed by independently evaluating the permissions for each of its roles.

In addition, Diffusion 6.5 added the ability to isolate paths. To convert a Diffusion 6.4 security store to an equivalent Diffusion 6.5 store, for each path in a path permission assignment for a role, add a separate statement to isolate the path. This produces a strictly equivalent model, but in practice it is typical that many of these path isolation statements can be removed without affecting an application's security policy, resulting in a simpler configuration.

Access control

To query the store the session needs VIEW_SECURITY permission and to update the store it needs MODIFY_SECURITY permission.

Accessing the feature

This feature can be obtained from a session as follows: 
 SecurityControl securityControl = session.feature(SecurityControl.class);
Since:
5.3
Author:
DiffusionData Limited