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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	SecurityControl.ConfigurationCallback Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
static interface	SecurityControl.ConfigurationContextCallback<C> Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
static interface	SecurityControl.Role Encapsulates the defined details for an individual role.
static interface	SecurityControl.ScriptBuilder A script builder may be used to create a script of commands to apply to the security store at the server.
static interface	SecurityControl.SecurityConfiguration Snapshot of information from the security store.

Nested classes/interfaces inherited from interface com.pushtechnology.diffusion.client.features.control.clients.SecurityStoreFeature

SecurityStoreFeature.UpdateStoreCallback, SecurityStoreFeature.UpdateStoreContextCallback<C>

Method Summary

Modifier and Type	Method and Description
CompletableFuture<SecurityControl.SecurityConfiguration>	getSecurity() Obtain the current contents of the security store.
<C> void	getSecurity(C context, SecurityControl.ConfigurationContextCallback<C> callback) Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
void	getSecurity(SecurityControl.ConfigurationCallback callback) Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
SecurityControl.ScriptBuilder	scriptBuilder() Returns a builder that can be used to create scripts for use with updateStore.

Methods inherited from interface com.pushtechnology.diffusion.client.features.control.clients.SecurityStoreFeature

updateStore, updateStore, updateStore

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature

getSession

Method Detail

getSecurity

CompletableFuture<SecurityControl.SecurityConfiguration> getSecurity()

Obtain the current contents of the security store.

Returns:

a CompletableFuture that completes when a response is received from the server.

If the request was successful, the CompletableFuture will complete successfully with a SecurityControl.SecurityConfiguration result.

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• PermissionsException – if the session does not have VIEW_SECURITY permission;
• SessionClosedException – if the session is closed.

Since:

6.0

getSecurity

@Deprecated
void getSecurity(SecurityControl.ConfigurationCallback callback)

Deprecated. since 6.7

Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.

Obtain the current contents of the security store.

Parameters:

callback - the operation callback

getSecurity

@Deprecated
<C> void getSecurity(C context,
                                 SecurityControl.ConfigurationContextCallback<C> callback)

Deprecated. since 6.7

Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.

Obtain the current contents of the security store, with a contextual callback.

Type Parameters:

C - the context type

Parameters:

context - the context to pass to the callback, may be null

callback - the operation callback

See Also:

getSecurity(ConfigurationCallback)

scriptBuilder

SecurityControl.ScriptBuilder scriptBuilder()

Returns a builder that can be used to create scripts for use with updateStore.

Returns:

an initial builder that creates an empty script