Role-based authorization

Associating permissions with roles

The association between roles and permissions is defined in the security store.

A set of permissions are defined for the system. In the security store, roles are defined. Roles include zero, one, or many permissions. Roles can also include other roles. Permissions can be associated with zero, one, or many roles.

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, installation_directory/persistence/Security.store, and 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 roles defined in the security store are associated with zero, one, or many principals.

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 installation_directory/persistence/SystemAuthentication.store, 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 Diffusion servers.

Assigning roles to client sessions

Roles are assigned to a new client session after client authentication.

When a client session connects or authenticates, it is assigned the roles associated with the session principal.

The roles assigned to a client session determine the actions that client session can perform.

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 store.
  - 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:

ALPHA
BETA
EPSILON
GAMMA
RHO

Authorizing actions

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 required permission.

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.