Namespace: security

Session. security

Security functionality. Allows querying and modification of server-side security and authentication configuration.

Example

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

Methods

authenticationScriptBuilder() → {SystemAuthenticationScriptBuilder}

Returns:
A script builder
Type
SystemAuthenticationScriptBuilder

changePrincipal(principal, credentials) → {Result.<undefined>}

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.

Parameters:
Name Type Description
principal String The new principal to use.
credentials String Credentials to authenticate the principal with.
Returns:
A Result.<undefined>.
Type
Result.<undefined>
Example
session.security.changePrincipal('foo', 'password');

getPrincipal() → {String}

Get the principal that the session is currently authenticated as.
Returns:
The session's principal
Type
String

getSecurityConfiguration() → {Result.<Session.security.SecurityConfiguration>}

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


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

Returns:
Type
Result.<Session.security.SecurityConfiguration>
Example
session.security.getSecurityConfiguration().then(function(configuration) {
    console.log('Got security configuration', configuration);
}, function(err) {
    console.log('Error getting security configuration', err);
});

getSystemAuthenticationConfiguration() → {Result.<Session.security.SystemAuthenticationConfiguration>}

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


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

Returns:
Type
Result.<Session.security.SystemAuthenticationConfiguration>
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);
});

securityScriptBuilder() → {SecurityScriptBuilder}

Returns a SecurityScriptBuilder that can be used to modify the server's Session.security.SecurityConfiguration.
Returns:
A script builder
Type
SecurityScriptBuilder

updateAuthenticationStore(Script) → {Result.<undefined>}

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.

Parameters:
Name Type Description
Script String The command script
Returns:
A Result.<undefined>
Type
Result.<undefined>
Example
session.security.updateAuthenticationStore(script).then(function() {
    console.log('Authentication configuration updated');
}, function(err) {
    console.log('Failed to update security configuration', err);
});

updateSecurityStore(Script) → {Result.<undefined>}

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.

Parameters:
Name Type Description
Script String The command script
Returns:
A Result.<undefined>
Type
Result.<undefined>
Example
session.security.updateSecurityStore(script).then(function() {
    console.log('Security configuration updated');
}, function(err) {
    console.log('Failed to update security configuration', err);
});

Type Definitions

GlobalPermission

Permissions that are applied globally. Allowed values are:

  • AUTHENTICATE - Add an authentication handler
  • VIEW_SESSION - List or listen to client sessions
  • MODIFY_SESSION - Alter a client session.
  • REGISTER_HANDLER - Required to register any server-side handler
  • VIEW_SERVER - View the server's runtime state
  • CONTROL_SERVER - Change the server's runtime state
  • VIEW_SECURITY - Read the security configuration
  • MODIFY_SECURITY - Change the security configuration
Type:
  • String

Role

Details for the permissions contained by a single role.
Properties:
Name Type Description
name String The name of the role
global Array.<Session.security.GlobalPermission> The list of global permissions
default Array.<Session.security.TopicPermission> The list of default topic permissions
topic Object.<String, Array.<Session.security.TopicPermission>> The map of topic paths to sets of Topic permissions
inherits Array.<String> The set of roles that this role inherits from

SecurityConfiguration

A snapshot of information from the security store.
Properties:
Name Type Description
named Array.<String> The list of default roles for named sessions
anonymous Array.<String> The list of default roles for anonymous sessions
roles Array.<Session.security.Role> The list of all defined roles

SystemAuthenticationConfiguration

A snapshot of information from the system authentication store.
Properties:
Name Type Description
principals Array.<Session.security.SystemPrincipal> The system principals stored on the server.
anonymous Object The configuration used for anonymous connections.
Properties
Name Type Description
action String The default action to apply to anonymous connections.

May be one of:

  • deny - Deny anonymous connection attempts.
  • allow - Accept anonymous connection attempts.
  • abstain - Defer authentication for anonymous connection attempts to subsequent authentication handlers
roles Array.<String> The roles assigned to anonymous connections.

SystemPrincipal

A principal in the system authentication store.
Type:
  • Object
Properties:
Name Type Description
name String The principal name
roles Array.<String> The principal's assigned roles

TopicPermission

Permissions that are applied on a topic path. Allowed values are:

  • 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.

    When the subscription or fetch request completes, the resulting topics are further filtered based on the READ_TOPIC permission.

    A session that has READ_TOPIC but not SELECT_TOPIC for a particular topic path cannot subscribe directly to topics belonging to the path. However, the session can be independently subscribed by a control session that has the MODIFY_SESSION global permission in addition to the appropriate SELECT_TOPIC permission.

  • READ_TOPIC - Required to receive information from a topic.

    If a session does not have read_topic permission for a topic, the topic will be excluded from the results of subscription or fetch operations for the session, and the topic's details cannot be retrieved by the session.

  • UPDATE_TOPIC - Update topics
  • MODIFY_TOPIC - Add or remove topics
  • SEND_TO_SESSION - Send a message another session
  • SEND_TO_MESSAGE_HANDLER - Send a message to a handler registered with the server
Type:
  • String