Permissions | Documentation

Permissions can have one of the following scopes:

Path: Permissions at path scope apply to actions on a topic path, request-response message path or session lock name.
Path-scoped permissions are defined against paths. The permissions that apply 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. Changes to the security store which alter read_topic permission assignments are applied dynamically. This means that if you change the permissions granted by a role, the new configuration is immediately applied to all sessions. Each session's topic selections are re-evaluated with the new permissions, and subscriptions are added or removed accordingly.
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 remove 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.

Configuring path permissions

You can configure path permissions using the client API or using the Security tab after logging in to Diffusion Cloud.

Understanding path permissions

Path permissions enable you to control access to resources that have a path-based hierarchy. The most common example is the topic tree, but request-response messaging paths and session lock names also use path permissions.

A session can carry out an action on a resource if any of its roles grants the appropriate permission for the resource path.

Each role assigns parts of the path hierarchy to permissions. The permissions a role grants for a path are determined by the assignment with the longest prefix of the path. For a given role, only one assignment applies to a path.

For example, suppose a session has two path permission rules for topics:

read_topic permission for the topic path telemetry/gps
read_topic and update_topic permission for the path telemetry/gps/ships

Consider the topic telemetry/gps/submarines/nautilus. Only the first rule matches the path, so the session would have read_topic permission for the topic.

Consider the topic telemetry/gps/ships/titanic. Both rules match, but the second rule is more specific, so the session has both read_topic and update_topic permission.

A session has a permission if any of its assigned roles has that permission (or includes a role that has that permission).

Note: This way of combining permissions from is a change from how it worked before version Diffusion Cloud 6.5. If you upgrade from 6.4 to 6.5, your existing configuration will be rewritten automatically to provide the same behavior as before. See Upgrading from version 6.4 to version 6.5 for details.

You can also define default path permissions. These are used if there are no matching path permissions and the path is not isolated (see below).

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

Isolating branches of the path hierarchy

Normally, if a role has no permission assignment for a path, the permissions are inherited from the permission assignment for the longest prefix of the path.

For example, if a role has no permission assigned for telemetry/gps/balloons, but it does have one for telemetry/gps, telemetry/gps/balloons will normally inherit the permissions.

Sometimes you may not want this inheritance to apply to a particular branch. For example, suppose your topic tree has this branch, with sensitive data that should only be accessed by sessions with a special role:

telemetry/gps/ships/glomar-explorer

If you grant another role read_topic permission to telemetry/gps/, sessions with that role will be able to read the sensitive branch.

One workaround would be to avoid creating any path permissions above telemetry/gps/ships/, but that means creating many more specific path permissions and updating them every time a new ship is added.

Isolating paths is a way to disable the usual inheritance rules and ignore default path permissions.

You can use the client API or the management console to create a rule that isolates a specified path.

In the above example, suppose you isolate telemetry/gps/ships/glomar-explorer. Now a role that has read_topic permission to telemetry/gps/ will not grant the ability to read the glomar-explorer topic or any of its children, such as telemetry/gps/ships/glomar-explorer/location.

In addition, a default path permission granting read_topic does not apply to the isolated path.

Path scope example

Diagram demonstrating path scope of different roles

This example demonstrates how path permissions and isolated paths combine.

The READER role has read_topic permission for path A, so a session with just this role can read the content of topic A. It can also read A/B and A/D, because the first part of the path matches and there are no conflicting permission rules.
The UPDATER role has update_topic permission for path A/B only.
A session with both READER and UPDATER roles combines the permissions above, granting read_update and update_topic permissions for A/B, as well as read access to A and A/D.

Note that if you had used a single role and granted read_update to A and update_topic to A/B, the session would not have both permissions to A/B, because only the more specific rule would be applied.
The path A/C is isolated, so normal inheritance rules do not apply. The READER role cannot read A/C (or any child topics like A/C/E).

The security store rules to configure this scenario would be:

set "READER" path "A" permissions [READ_TOPIC]
set "UPDATER path "A/B" permissions [UPDATE_TOPIC]
isolate path "A/C"

See DSL syntax: security store for details.

Understanding the select_topic and read_topic permissions

The default configuration grants the select_topic and read_topic permissions to CLIENT sessions including anonymous sessions. 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.

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	Server control functions: create or modify remote server definitions create or modify metric collectors
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.