Diffusion™ restricts the ability to perform actions to
authorized principals. Roles are used to map permissions to principals.
Associating permissions with roles
The association between roles and permissions is defined in the security
A fixed set of permissions is defined by the Diffusion server. These
permissions are used to control access to actions and data on the Diffusion server.
Roles are used to associate permissions to principals. Permissions are assigned to roles,
and roles are assigned to principals.
A role can be assigned zero, one, or many permissions. The same permission can be assigned
to multiple roles. Roles can also include other roles to form a role hierarchy, and so
inherit their permissions. The permissions assigned to a role and the role hierarchy are
defined in the security store.
You can update the security store from a client using the SecurityControl feature.
You can update the security store by editing the store file,
restarting the Diffusion server. Note that if you have never started the server,
the file is not found in the persistence directory; an initial file
is in installation_directory/etc, and this
is copied into the persistence directory when you first start the server.
You should stop the server before editing the system authentication store directly.
If you are using a cluster, all the servers in the cluster should be stopped before editing.
If the server or cluster is running, changes should be made using the management console or the API.
Associating roles with principals
The association between roles and principals is defined in the system
authentication store or by user-written authentication handlers.
The association between principals and roles is defined in the following ways:
In a user-defined store that your user-written authentication handlers refer to. For
example, an Lightweight Directory Access Protocol (LDAP) server.
A user-written authentication handler can also hard code the relationship between
principals and roles, if that is appropriate.
In the system authentication store of the Diffusion server
The system authentication store is designed to hold information
about Diffusion administration users and system clients. It can
manage hundreds or perhaps thousands of principals, but does not provide the administration
tools necessary to support millions of principals. We recommend that you delegate such
"internet scale" use cases to a third-party identity provider using a custom authentication
handler. For example, by using the OAuth or OpenID protocol.
You can update the system authentication store in the following ways:
From a client using the SystemAuthenticationControl feature.
By editing the store file, by default found at
and restarting the Diffusion server. Note that if you have never started the server,
the file will not be found in the persistence directory; an example file
will be found in installation_directory/etc, and this
is copied into the persistence directory when you first start the server.
It is recommended that you update the store from a client instead
of editing the file directly. Do not edit the store file if you are using clustered
Assigning roles to client sessions
Roles are assigned to a new client session after client authentication.
The roles assigned to a client session determine the actions that client session can
A client session is assigned roles in the following ways:
If the client session connects to the Diffusion server anonymously, the
client session is assigned the default assigned roles for the ANONYMOUS principal.
Anonymous authentication can be enabled or disabled in the system authentication
store. If enabled, roles can also be specified.
When a client session authenticates with a principal, the client session can be
assigned the following roles:
The default assigned roles for a named principal.
The set of roles assigned to a principal by the authentication handler that
accepts the client session's authentication request. This authentication handler can
be one of the following types:
The system authentication handler, in which case the roles that are assigned
are those associated with that principal in the system authentication
A user-written authentication handler, in which case the roles that are
assigned are those defined by the handler or a user-defined store.
A client session with the correct privileges can change the security roles
assigned to another session. This requires modify_session
and view_session permissions.
For example: A client session authenticates with the Diffusion server using
the principal Armstrong. The first authentication
handler that is called is a user-written authentication handler. This authentication handler
abstains from the authentication decision, so does not assign roles to the client session.
The next authentication handler that is called is the system authentication handler. The
system authentication handler does not abstain from the authentication decision. It uses the
information in the system authentication store to decide to allow the authentication
request. In the system authentication store, the principal Armstrong is associated with the roles ALPHA, BETA, and EPSILON. These roles are assigned to the client session.
After the authentication request has been allowed, no further authentication handlers
are called to make a decision or assign roles. However, the Diffusion server
also assigns the default assigned roles for a named principal to the client session. The
default assigned roles defined in the security store are GAMMA and RHO.
After authenticating with the principal Armstrong, the client session has the following roles assigned to it:
When a client requests to perform an action or access data that requires a permission, the Diffusion server checks whether the client session is assigned a role that
includes the required permission.
The client requests to perform an action. If the action requires that the client
session has a permission, the Diffusion server checks what roles the client
session is assigned and checks in the security store whether any of these roles have the
For example: A client requests to subscribe to the topic A/B/C. To subscribe to a topic, a client session must have the select_topic permission for that topic. The client
session has the ALPHA and BETA roles. In the security store, the ALPHA role does not include the select_topic permission, but the BETA role does include the select_topic permission for the A/B/C topic. Because the client session is assigned the
BETA role, it has the required permission and
can subscribe to the topic.
Locking Principals and Roles
Users with sufficient permission may modify permissions associated with principals and
roles. However, this could allows users to inadvertently put themselves in an unrecoverable
state where they remove the ability to edit security settings from themselves.
To overcome this a Diffusion administrator may mark certain principals and roles as
"locked", whereby modifications are only permitted by a specified principal.
Generally, MODIFY_SECURITY permission is sufficient to modify any
principal or role in the security and system authentication stores. However, it is possible
to optionally associate a principal or role with a principal that can edit it.
The syntax for creating a principal is:
add principal 'name' 'password' locked by 'lock_principal'.
The syntax for locking a role is:
set role 'role_name' locked by 'lock_principal'
The locking principal still requires the MODIFY_SECURITY permission to
modify the store.