Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface Security

This feature allows a client session to query and update the security store and to authenticate the credentials of other sessions.

Authentication Control

Sessions are authenticated by a chain of authenticators. A client session can participate in the authentication process by creating an authenticator and registering it with the server.

Each authenticator is registered under a particular authenticator name. For registration to succeed, the server's security configuration must include a matching control-authentication-handler entry for the name, otherwise registration will fail and the authenticator will be closed immediately.

Each client session can register a single authenticator for a given authenticator name.

For each authentication event, the server will use its configuration to determine the authenticator priority order. The server may call authenticators in serial or parallel. The server may stop the authentication process as soon as it has an allow or deny response from an authenticator and all higher priority authenticators have abstained.

For a configured control authenticator, the server will select a single authenticator from those registered for the authenticator name. If no authenticators are currently registered, the server will consult the next configured authenticator in priority order.

Access control

In order to register an authenticator a session needs both REGISTER_HANDLER and AUTHENTICATE permissions.

In order to revoke a session's authentication a session needs both MODIFY_SESSION and AUTHENTICATE permissions.

Security Control

The security store is a persistent database maintained by the server containing authorisation rules that control what sessions can do.

Access rights to read and write data and to perform actions on the server are controlled by a fixed set of permissions. When a session is opened, the server assigns it a set of roles based on the principal used to authenticate. The rules in the security store assign each role to a set of permissions. Each 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 permissions from the other roles. Roles are defined implicitly by specifying them in permission assignments or inclusion relationships; there is no need to explicitly create roles in the security store.

Permissions either have 'path' or 'global' scope. Global permissions apply to actions that are server-wide and not specific to a particular path. Path permissions apply to hierarchical context, such as a branch of the topic tree or a branch of the message path hierarchy.

Evaluation of global permissions

A session has a global permission if any of its roles are assigned the permission.

Evaluation of path permissions

A session has a permission for a path if any of its roles have the permission for the path.

Path permissions can be assigned to a role for a path. The permissions are inherited by all descendant paths for the role, except paths that have a separate permission assignment for the role or that are isolated and their descendant paths.

Default path permissions can be assigned to a role to set permissions at the root of the path hierarchy. A default permission assignment applies to all paths without direct or inherited path permission assignments, except paths that are isolated and their descendant paths.

The permissions a session has for a path are determined as follows:

  1. If the path has permission assignments for one or more of the sessions roles, the applicable permissions are the union of all of the assigned permissions.
  2. Otherwise, if the path is not isolated, and its parent path has permission assignments for one or more of the sessions roles, the applicable permissions are the union of all of the permissions assigned to the parent path. This rule is applied recursively, for each remaining parent path.
  3. Otherwise, if the neither the path nor any of its parent paths have permission assignments for one of the sessions role or are isolated, the applicable permissions are the union of the default permissions assigned to each role.
  4. If no applicable permissions are found, the session has no permissions for that path.

Access control

To query the store the session needs VIEW_SECURITY permission and to update the store it needs MODIFY_SECURITY permission.

In order to register an authentication handler a session needs both REGISTER_HANDLER and AUTHENTICATE permissions.

Accessing the feature

This feature can be obtained from a session as follows:

Example:

// Get a reference to the security feature
var security = session.security;

Hierarchy

  • Security

Index

Properties

GlobalPermission

GlobalPermission: GlobalPermission

The global permission enum

PathPermission

PathPermission: PathPermission

The path permission enum

Methods

authenticationScriptBuilder

changePrincipal

  • changePrincipal(principal: string, credentials: string): Promise<void>
  • Change the principal associated with this session.

    Allows a session to authenticate as a different principal. If the authentication fails, the current principal remains valid.

    deprecated

    since 6.12 Use the new reauthenticate in preference, which allows user proposed session properties to be supplied. This method will be removed in a future release.

    Parameters

    • principal: string

      the new principal to use.

    • credentials: string

      credentials to authenticate the principal with.

    Returns Promise<void>

    a {@link Promise}

    Example:

    session.security.changePrincipal('foo', 'password');

getGlobalPermissions

  • Returns the set of global permissions assigned to the role.

    since

    6.3

    Returns Promise<GlobalPermission[]>

    the set of global permissions. This may be empty indicating that the role has no global permissions assigned.

getPathPermissions

  • Returns a list of path permissions assigned to the calling session on a given path.

    since

    6.5

    Parameters

    • path: string

      the path to query for permissions

    Returns Promise<PathPermission[]>

    a {@link Promise} which completes when the response is received from the server.

    If the request was successful, the {@link Promise} will complete successfully with a list of PathPermission.

getPrincipal

  • getPrincipal(): string
  • Get the principal that the session is currently authenticated as.

    Returns string

    the session's principal

getSecurityConfiguration

  • Obtain the current contents of the server's security store.

    If the request is successful, the result will complete with a SecurityConfiguration.

    Example:

    session.security.getSecurityConfiguration().then(function(configuration) {
        console.log('Got security configuration', configuration);
    }, function(err) {
        console.log('Error getting security configuration', err);
    });

    Returns Promise<SecurityConfiguration>

    a {@link Promise} that completes with the security configuration

getSystemAuthenticationConfiguration

  • Obtain the current contents of the server's authentication store.

    If the request is successful, the success callback will be called with a SystemAuthenticationConfiguration object.

    Example:

    session.security.getSystemAuthenticationConfiguration().then(function(configuration) {
         // Display principals/roles
         configuration.principals.forEach(function(principal) {
              console.log(principal.name, principal.roles);
         });
    
         // Check the authentication action applied to anonymous connections
         console.log(configuration.anonymous.action);
    
         // Check the default roles assigned to anonymous connections
         console.log(configuration.anonymous.roles);
    }, function(err) {
         // Error retrieving configuration
         console.log(err);
    });

    Returns Promise<SystemAuthenticationConfiguration>

    a {@link Promise} that completes with the server's authentication store

reauthenticate

  • Re-authenticate the session.

    This may be used to change the principal for the session, or to re-authenticate the session before it expires.

    A session may determine when it is due to expire by querying the value of the EXPIRY_TIME session property using Session.getSessionProperties. If this property is not present the session will not expire and there is no need to re-authenticate unless the principal in use is to be changed.

    since

    6.12

    Parameters

    • principal: string

      the principal name. This may be the same principal as supplied when the session was originally opened, or it may be an entirely different principal.

    • credentials: Credentials

      the credentials authenticating the principal

    • properties: SessionProperties

      a map of the proposed user session properties. The supplied properties will be validated during authentication and may be discarded or changed. If no user properties are required, an empty object should be supplied.

    Returns Promise<boolean>

    a Promise that resolves when a response is received from the server.

    If authentication succeeded, the Promise will resolve with true.

    If authentication failed because the {@code principal} was unknown or the {@code credentials} were invalid, the session will not have been re-authenticated and the Promise will resolve with false.

    Otherwise, the Promise will be rejected with an error.

    Common reasons for failure include:

    • the session is closed.

revokeAuthentication

  • revokeAuthentication(sessionId: SessionId): Promise<void>
  • Revokes a session's authentication.

    This will immediately close the specified client session.

    since

    6.12

    Parameters

    • sessionId: SessionId

      identifies the client session to revoke

    Returns Promise<void>

    a {@link Promise} which completes when the response is received from the server.

securityScriptBuilder

setAuthenticator

  • Register an authenticator for client authentication events.

    since

    6.3

    Parameters

    • handlerName: string

      the handler name which must match an entry in the server's security configuration

    • authenticator: Authenticator

      specifies the authentication handler

    Returns Promise<Registration>

    a {@link Promise} that completes when the authentication handler has been registered, returning a Registration which can be used to unregister the authentication handler.

    Otherwise, the Promise will resolve with an error. Common reasons for failure include:

    • the session is closed;
    • the session does not have REGISTER_HANDLER or AUTHENTICATE permission;
    • the server configuration does not contain a control-authentication-handler element with the given name.
    • NullValueError – if any of the arguments are null or undefined

updateAuthenticationStore

  • updateAuthenticationStore(script: string): Promise<void>
  • Send a command script to the server to update the authentication store. The script may be produced by the builder SystemAuthenticationScriptBuilder.

    If the script is applied without error to the server, the operation result will complete successfully.

    If any command in the script fails, none of the changes will be applied, and the result will be failed with an error object.

    If the server is configured for path replication then the changes will be replicated to all members of the cluster.

    Example:

    session.security.updateAuthenticationStore(script).then(function() {
        console.log('Authentication configuration updated');
    }, function(err) {
        console.log('Failed to update security configuration', err);
    });

    Parameters

    • script: string

      the command script

    Returns Promise<void>

    a {@link Promise}

updateSecurityStore

  • updateSecurityStore(script: string): Promise<void>
  • Send a command script to the server to update the security store. The script may be produced by the builder SecurityScriptBuilder.

    If the script is applied without error to the server, the operation result will complete successfully.

    If any command in the script fails, none of the changes will be applied, and the result will be failed with an error object.

    If the server is configured for path replication then the changes will be replicated to all members of the cluster.

    Example:

    session.security.updateSecurityStore(script).then(function() {
        console.log('Security configuration updated');
    }, function(err) {
        console.log('Failed to update security configuration', err);
    });

    Parameters

    • script: string

      the command script

    Returns Promise<void>

    a {@link Promise}