Permissions

Permissions determine the actions a client session can take in Diffusion® Cloud.
Permissions are granted through roles. Thus, a session gets its permissions based on the roles it is assigned.

Permissions are broadly categorised into:

Global permissions
Path permissions

Global Permissions

These are permissions that apply to the whole Diffusion® Cloud server.
For example, a session can have permission to list all other sessions, or to restart the Diffusion® Cloud server.

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 subscribe a session to a topic, enable conflation for a session or close a session.
`register_handler`	Register any handler with the Diffusion® Cloud server.
`authenticate`	Register an authentication handler. The `register_handler permission` is also required to perform this action.
`view_server`	Read administrative information about the Diffusion® Cloud server. For example, through Java Management Extensions (JMX).
`control_server`	Shut down the Diffusion® Cloud server. This action can be taken only from the console. Client sessions cannot shut down the Diffusion® Cloud server.
`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.

Path Permissions

These are permissions that apply to a topic path or request-response message path.
A path permission grants the ability to perform an action on topics/messages on a certain path.

Path 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, the topic does not match subscriptions, is excluded from fetch requests, and it’s topic details cannot be retrieved. Changes to the security store which alter the `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 the `update_topic` permission.
`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 the `update_topic` permission.
`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 the Diffusion® Cloud server through a message path.
`send_to_session`	Send a message to a client session through a message path.

Path permissions with a single role

A path permission is associated with a path.
For example, if a client session has read_topic permission for the topic path telemetry/gps (and no other permissions) it can read that topic and all descendant topics, such as telemetry/gps/ships.
If a session has multiple path permissions from the same role, the most specific permission is applied, i.e. the permission with the longest matching path.
So, if the same session is granted update_topic permission for telemetry/gps/ships/titanic by the same role, it will have update_topic for telemetry/gps/ships/titanic and descendant topics - but not read_topic.

Path permissions from multiple roles

A session can have more than one role.
A session has a permission if any of its assigned roles has that permission
For example, if a session is granted read_topic on path a/b by the READER role, and update_topic on path a/b by the UPDATER role, it will have both the permissions on that path.

Default path permissions

You can define default path permissions.
These are used if there are no matching path permissions and the path is not isolated.
For example, if you want anonymous clients to be able to read any topic by default, you can set a default read_topic permission to the ANONYMOUS role.

Isolating paths

Path permissions are normally inherited from higher path levels.
For example, if a client session has read_topic permission for the path telemetry/gps, it can also read descendants like telemetry/gps/ships.

However, in some cases, you may have a branch that you want to manage separately.
For example, you have sensitive data in telemetry/gps/ships/secret/.
You still want to be able to grant read_topic for telemetry/gps to normal client, but you don’t want them to be able to read the secret branch.

To handle this, you can use the client API to isolate the path.
This disables the usual inheritance rules and any default path permissions.
You can then use a separate role to grant permissions to the specific path (or its descendants).