Interface ISecurityControl

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.

Inherited Members
Namespace: PushTechnology.ClientInterface.Client.Features.Control.Clients.SecurityControl
Assembly: Diffusion.Client.dll
Syntax
public interface ISecurityControl : ISecurityStoreFeature, IFeature
Remarks

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. GlobalPermission apply to actions that are server-wide and not specific to a particular path. PathPermission 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.

SetPathPermissions(String, String, IEnumerable<PathPermission>) 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 IsolatePath(String) and their descendant paths.

SetDefaultPathPermissions(String, IEnumerable<PathPermission>) 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 IsolatePath(String) 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 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

In order to query the store the session needs VIEW_SECURITY permission and in order to update the store it needs MODIFY_SECURITY permission.

Accessing the feature

This feature may be obtained from an ISession as follows: 

var securityControl = session.SecurityControl;

Added in version 5.3.

Properties

Script

Gets the builder that can be used to create scripts for use with UpdateStore(String, IUpdateStoreCallback).

Declaration
IScriptBuilder Script { get; }
Property Value
Type Description
IScriptBuilder

The default builder instance that creates an empty script.

Methods

GetSecurity(IConfigurationCallback)

Obtains the current contents of the security store.

Declaration
void GetSecurity(IConfigurationCallback callback)
Parameters
Type Name Description
IConfigurationCallback callback

The callback to receive status notifications for this operation.
Remarks

Caution

Deprecated since 6.7. Methods that use callbacks are deprecated and will be removed in a future release. Use a Task instead.

GetSecurity<TContext>(TContext, IConfigurationContextCallback<TContext>)

Obtains the current contents of the security store.

Declaration
void GetSecurity<TContext>(TContext context, IConfigurationContextCallback<TContext> callback)
Parameters
Type Name Description
TContext context

The context of this operation.
IConfigurationContextCallback<TContext> callback

The callback to receive status notifications for this operation.
Type Parameters
Name Description
TContext

The context type.
Remarks

Caution

Deprecated since 6.7. Methods that use contextual callbacks are deprecated and will be removed in a future release. Use a Task instead.

GetSecurityAsync()

Obtains the current contents of the security store.

Declaration
Task<ISecurityConfiguration> GetSecurityAsync()
Returns
Type Description
Task<ISecurityConfiguration>

The Task representing the current operation.
Remarks

If the operation completes successfully, the Task result will be a ISecurityConfiguration instance.

This method is the same as calling GetSecurityAsync(CancellationToken) with System.Threading.CancellationToken.None.

Exceptions
Type Condition
SessionSecurityException

The calling session does not have VIEW_SECURITY permission. Thrown by the returned Task.
SessionClosedException

The calling session is closed. Thrown by the returned Task.

GetSecurityAsync(CancellationToken)

Obtains the current contents of the security store.

Declaration
Task<ISecurityConfiguration> GetSecurityAsync(CancellationToken cancellationToken)
Parameters
Type Name Description
CancellationToken cancellationToken

The cancellation token used to cancel the current operation.
Returns
Type Description
Task<ISecurityConfiguration>

The Task representing the current operation.
Remarks

If the operation completes successfully, the Task result will be a ISecurityConfiguration instance.

Exceptions
Type Condition
SessionSecurityException

The calling session does not have VIEW_SECURITY permission. Thrown by the returned Task.
SessionClosedException

The calling session is closed. Thrown by the returned Task.