Expand Collapse
Just a second...

Permissions

The actions a client session can take in Diffusion™ Cloud are controlled by a set of permissions. These permissions are assigned to roles.

Permissions can have one of the following scopes:
Path
Permissions at path scope apply to actions on a topic path or message path.

Path-scoped permissions are defined against paths. The permissions that apply to a topic path or to a message path are the set of permissions defined at the most specific path.

Global
Permissions at global scope apply to actions on Diffusion Cloud.

Path permissions

The path-scoped permissions are listed in the following table:

Table 1. List of path-scoped permissions
Name Description
acquire_lock Acquire a session lock. The names of the locks that can be acquired are restricted to the paths of the permission scope.
select_topic Use a topic selector that selects the topic path. A session must have this permission for the path prefix of any topic selector used to subscribe or fetch.
read_topic Grant read access to the topics.

If a session does not have this permission for a topic, that topic does not match subscriptions and is excluded from fetch requests. Also, the topic's details cannot be retrieved.
query_obsolete_time_series_events Evaluate a query on a time series topic that can potentially return a non-current view of all or part of a time series. Such queries include value range queries that specify an edit range, and all types of edit range query. Evaluating a query also requires read_topic.
edit_time_series_events Submit edit events to a time series topic. Updating a time series topic also requires update_topic.
edit_own_time_series_events Submit edit events to a time series topic where the event author is the same as the principal of the calling session. Updating a time series topic also requires update_topic.
update_topic Update topics at or below a topic branch.
modify_topic Create or modify topics at or below a topic branch.
send_to_message_handler Send a message to Diffusion Cloud through a message path.
send_to_session Send a message to a client session through a message path.

Understanding path-scoped permissions

Path-scoped permissions are assigned to roles for specific paths. The permission assignment applies to all descendant paths, unless there is a more specific assignment.

To evaluate whether a client session has access to a permission for a topic or message path, Diffusion Cloud starts at that path and searches up the path hierarchy to find the nearest permission assignment. The first assignment is the only one considered, even if the client has roles involved in assignments further up the path hierarchy.

Default path-scoped assignments can also be defined. These are used if no path assignment matches.

The flowchart steps through the process Diffusion uses to evaluate whether a client session has the necessary permission to complete an action at a topic path.

The path-scoped permissions included in the set of roles that are predefined in Diffusion Cloud are all scoped to the whole path hierarchy.

Path scope example

The diagram shows the structure of a topic tree. The topic 'A' has path 'A'. The topic 'B' is below topic 'A' and has path 'A/B'. The topic 'C' is below topic 'A' and has path 'A/C'. The topic 'D' is below topic 'C' and has path 'A/C/D'. Permissions are defined for the following topics: 'A', 'C', and 'D'. At topic 'A', the role 'ALPHA' has read_topic, update_topic, and modify_topic permissions. At topic 'C', the role 'ALPHA' has no permissions defined, the role 'BETA' has read_topic and update_topic permissions. At topic 'D', the role 'ALPHA' has read_topic and update_topic permissions, the role 'BETA' has read_topic and update_topic permissions.
In this example, client sessions with the role ALPHA have the following permissions on each topic in the topic tree:
A
A permission set is defined for the path A.

These permissions give client sessions with the ALPHA role read_topic, update_topic, and modify_topic permissions on the topic A.

A/B
No permission set is defined for the path A/B. In this case, the permissions at the most specific scope are those defined for the path A

These permissions give client sessions with the ALPHA role read_topic, update_topic, and modify_topic permissions on the topic B.

A/C
A permission set is defined for the path A/C. These permissions do not include any permissions for the ALPHA role.

Client sessions with the ALPHA role have no permissions on the topic C. Permissions are defined for the ALPHA role at a less specific scope. However, these permissions are not referred to or inherited if any permissions are defined at a more specific scope. Only the most specific set of permissions is used. In this case, those permissions are only for the BETA role and not the ALPHA role.

A/C/D
A permission set is defined for the path A/C/D.

These permissions give client sessions with the ALPHA role read_topic and update_topic permissions on the topic D.

The role ALPHA has only these permissions even though at A/C the role has no permissions defined and at A the role has additional permissions. Only the most specific set of permissions is used.

The BETA role also has permissions defined at this scope. These permissions do not affect the permissions that the ALPHA role has at this scope.

Understanding the select_topic and read_topic permissions

The default configuration grants the select_topic and read_topic permissions to all sessions then protects the topics on paths below the Diffusion path using the OPERATOR role. You can alter this configuration to protect sensitive topics.

A session that does not have the select_topic permission for a particular path cannot subscribe directly to topics at that path. However, the session can be independently subscribed to that topic by a control session that has modify_session permission in addition to the select_topic permission for that path. The subscribed session requires the read_topic permission for that topic for the subscription to the topic to occur. The control session cannot subscribe a session to a topic if that session does not have the read_topic permission for the topic. When this occurs, the topic is filtered out of the subscription.

Use the select_topic permission with some care because topic selectors can use wild card expressions. For example, with the default configuration, the OPERATOR role is required to use topic selector expressions such as Diffusion or ?Diffusion//", but the CLIENT role is sufficient to use the topic selector expression ?// which selects all of the topics in the topic tree.

In the default configuration, this does not cause a problem as sessions that do not have the OPERATOR role also do not have the read_topic permission for topic paths below Diffusion. Any matching topics are filtered from subscription and fetch results for those sessions.

Managing all subscriptions from a separate control session

You can prevent client sessions from subscribing themselves to topics and control all subscriptions from a separate control client session that uses SubscriptionControl feature to subscribe clients to topics.

To restrict subscription capability to control sessions, configure the following permissions:

Control session:
  • Grant the modify_session permission
  • Grant the select_topic permission

    This can either be granted for the default path scope or more selectively to restrict the topic selectors the control session can use.

Other sessions:
  • Grant read_topic to the appropriate topics.
  • Deny the select_topic permission by default.

    Do not assign the session a role that has the select_topic permission for the default path scope. This prevents the session from subscribing to all topics using a wildcard selector.

  • Optionally, grant the select_topic permission to specific branches of the topic tree to which the session can subscribe freely.

Global permissions

The global permissions are listed in the following table:

Table 2. List of global permissions
Name Description
view_session List or listen to client sessions.
modify_session Alter a client session. This covers a range of actions including the following:
  • subscribe a session to a topic
  • throttle a session
  • enable conflation for a session
  • close a session
register_handler Register any handler with Diffusion Cloud.
authenticate Register an authentication handler.

The register_handler permission is also required to perform this action.
control_server
Shut down Diffusion Cloud.
Note: This action can be taken only from the dashboard. Client sessions cannot shut down Diffusion Cloud.
view_security View the security policy.
modify_security Change the security policy.
read_topic_views View the topic views.
modify_topic_views Change the topic views. To add a new topic view the session also needs the select_topic permission for the prefix of the source selector of the topic view being added.

This page last modified: 2019/11/22