Permissions at global scope apply to actions on the Diffusion server.
The path-scoped permissions are listed in the following table:
Table 1. List of path-scoped permissions
Acquire a session lock. The names of the locks that can be acquired are
restricted to the paths of the permission scope.
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.
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.
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.
Submit edit events to a time series topic. Updating a time series topic also requires
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 topics at or below a topic branch.
Create or modify topics at or below a topic branch.
Send a message to the Diffusion server through a message
Send a message to a client session through a message path.
Configuring path permissions
Path permissions are stored as rules in the system security store.
You should create and update them via a client using the API, or using the
Diffusion management console.
See Configuring security
and the API documentation for your SDK for more details.
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:
permission for the topic path telemetry/gps
and update_topic permission for the path
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
Note: This way of combining permissions from
is a change from how it worked before version Diffusion 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).
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:
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
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
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
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"
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
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
To restrict subscription capability to control sessions, configure the following
Grant the modify_session permission
Grant the select_topic permission
can either be granted for the default path scope or more selectively to restrict the
topic selectors the control session can use.
Grant read_topic to the appropriate
Deny the select_topic permission by
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
Optionally, grant the select_topic
permission to specific branches of the topic tree to which the session can subscribe
The global permissions are listed in the following table:
Table 2. List of global permissions
List or listen to client sessions.
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 any handler with the Diffusion server.
Register an authentication handler.
The register_handler permission is also required to perform this
Read administrative information about the Diffusion server.
For example, through Java Management Extensions (JMX).
Server control functions:
create or modify remote server definitions
create or modify metric collectors
shut down the Diffusion server (via JMX)
start and stop and remove connectors (via JMX)
start and stop HTTP services (via JMX)
clear the HTTP file service cache (via JMX)
View the security policy.
Change the security policy.
View the topic views.
Change the topic views. To add a new topic view the session also needs the
for the prefix of the source selector of the topic view being added.