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:
Topic
Permissions at topic scope apply to actions on a topic.

Topic-scoped permissions are defined against topic branches. The permissions that apply to a topic are the set of permissions defined at the most specific branch of the topic tree.

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

Topic permissions

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

Table 1. List of topic-scoped permissions
Name Description
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 topics details cannot be retrieved.
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 topic message to the server for a topic at or below a topic branch.
send_to_session Send a message to a client session for a topic at or below a topic branch.

Understanding topic-scoped permissions

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

To evaluate whether a client session has access to a permission for a topic, Diffusion Cloud starts at that topic and searches up the tree 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 topic tree.

Default topic-scope 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 topic-scoped permissions included in the set of roles that are predefined in Diffusion Cloud are all scoped to the whole path hierarchy.

Figure 1. Topic 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 topic 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 topic path A/B. In this case, the permissions at the most specific scope are those defined for the topic 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 topic 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 topic 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 topic tree below the Diffusion topic 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 topic 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 topic 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 topics 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 topic 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 topic 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.

This page last modified: 2017/06/05