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()
-
Returns a SystemAuthenticationScriptBuilder that can be used to modify the server's Session.security.SystemAuthenticationConfiguration.
Returns:
A script builder
-
changePrincipal(principal, credentials)
-
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()
-
Get the principal that the session is currently authenticated as.
Returns:
The session's principal
- Type
- String
-
getSecurityConfiguration()
-
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:
A 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()
-
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:
A 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()
-
Returns a SecurityScriptBuilder that can be used to modify the server's Session.security.SecurityConfiguration.
Returns:
A script builder
-
setAuthenticationHandler(handlerName, requestedDetails, handler)
-
Register a handler for client authentication events.
Each handler is registered under a particular
handlerName
. For registration to succeed, the server's security configuration must include a matching
entry for the name. Otherwise registration will fail, the handler will be closed immediately, and an error will be reported to the session error handler.Each control session can register a single handler for a
handlerName
. See AuthenticationHandler#onActive.It is normal for several or all of the control sessions in a control group to set a handler for a given name. Registration will fail if a session in a different control group has registered a handler using the name.
For each authentication event, the server will use its configuration to determine the handler priority order. The server can call authentication handlers in serial or parallel. The server can stop the authentication process as soon as it has an allow or deny response from a handler and all higher priority handlers have abstained.
For a configured control authentication handler, the server will select a single handler from those registered for the
handlerName
. If no handlers are currently registered, the server will consult the next handler.Parameters:
Name Type Description handlerName
String must match an entry in the server's security configuration for registration to succeed
requestedDetails
Array.<diffusion.clients.DetailType> the session details that the server will supply, if available
handler
AuthenticationHandler the authentication handler to set
Examples
// Set a simple handler to handle pre-defined principals, otherwise defer to default handling session.security.setAuthenticationHandler('before-system-handler', [], { onAuthenticate : function(principal, credentials, details, callback) { if (principal === 'alice' && credentials === 'hello') { callback.allow(); } else if (principal === 'bob') { callback.deny(); } else { callback.abstain(); } }, onActive : function(deregister) { }, onClose : function() { }, onError : function() { } });
// Set a handler that allocates roles & properties to certain sessions session.security.setAuthenticationHandler('before-system-handler', [diffusion.clients.DetailType.SUMMARY], { onAuthenticate : function(principal, credentials, details, callback) { if (details.summary.clientType === diffusion.clients.ClientType.IOS && details.summary.transportType === diffusion.clients.TransportType.WEBSOCKET) { // Session will be authenticated with the 'WS_IOS' role, and an assigned session property callback.allow({ roles : ['WS_IOS'], properties : { PropertyName : 'PropertyValue' } }); } else { callback.abstain(); } }, onActive : function(deregister) { }, onClose : function() { }, onError : function() { } });
-
updateAuthenticationStore(Script)
-
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)
-
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 handlerVIEW_SESSION
- List or listen to client sessionsMODIFY_SESSION
- Alter a client session.REGISTER_HANDLER
- Required to register any server-side handlerVIEW_SERVER
- View the server's runtime stateCONTROL_SERVER
- Change the server's runtime stateVIEW_SECURITY
- Read the security configurationMODIFY_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.
deny
- Deny anonymous connection attempts.allow
- Accept anonymous connection attempts.abstain
- Defer authentication for anonymous connection attempts to subsequent authentication handlers
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:
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 notSELECT_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 theMODIFY_SESSION
global permission in addition to the appropriateSELECT_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 topicsMODIFY_TOPIC
- Add or remove topicsSEND_TO_SESSION
- Send a message another sessionSEND_TO_MESSAGE_HANDLER
- Send a message to a handler registered with the server
Type:
- String