Callback Scripts
The Smile CDR Inbound and Outbound Security modules support a JavaScript based callback API that can be used to add custom logic to the authentication and authorization process. Callback scripts have the right to examine authentication requests, enhance or restrict the corresponding user session, and even reject the authentication entirely.
The onAuthenticateSuccess method is invoked after a user has successfully authenticated with an inbound security module. In other words, this is invoked after a user's credentials have been validated and a set of user details (potentially including the user's name, permissions, etc.) has been assembled.
The script has the ability to modify the user's details. This might consist of steps such as:
theUserSession – This object contains details about the request, including the authorization and authentication tokens. This object is of type UserSessionDetails.
theOutcomeFactory – This object is used to create a success or failure object to be returned by the function. This object is of type ScriptAuthenticationOutcomeFactory.
theContext – The context object contains details about the environment in which the authorization occurred. The datatype for this object will vary depending on the specific inbound security module being used. See the individual module type documentation for more information. All module types will provide a context that provides at least the properties and functions of the AuthenticationContext. Different Inbound Security modules will provide a specific subclass of AuthenticationContext that has relevant properties and operations for that module type:
The following is a simple example of an onAuthenticateSuccess callback function:
function onAuthenticateSuccess(theOutcome, theOutcomeFactory, theContext) {
var username = theOutcome.username;
var remoteAddress = theContext.remoteAddress;
Log.info('User ' + username + ' is logging in from ' + remoteAddress);
// Don't allow the admin user to log in from hosts other than localhost
// Note that the username will be capitalized if the security module is not case sensitive
if (username === 'ADMIN' && remoteAddress != '127.0.0.1') {
var failure = theOutcomeFactory.newFailure();
failure.message = 'Can not log in as admin from this address';
return failure;
}
// Otherwise, just return default (successful) outcome
return theOutcome;
}
Typically, it is sufficient to simply return the authorization outcome that was already generated by the system as shown above. It is also possible to modify the authorization. The most common use case is to add or remove permissions based on some criteria.
function onAuthenticateSuccess(theOutcome, theOutcomeFactory, theContext) {
if (theOutcome.username === 'admin123') {
theOutcome.addAuthority('ROLE_FHIR_CLIENT_SUPERUSER_RO');
}
return theOutcome;
}
The following example shows a failure being returned:
// Create a failure object to return
var failure = theOutcomeFactory.newFailure();
// The following properties are optional
failure.message = 'Login failed due to invalid credentials';
failure.unknownUsername = false;
failure.incorrectPassword = true;
return failure;
Note the properties that may optionally be populated on the failure object. These properties supply additional details about the failure and can be useful for troubleshooting; however, they are not required to be populated. A failure object with no properties is still treated as a normal authentication failure.
message property is used to supply a human-readable description of why the authentication failed.unknownUsername property may be set to true to indicate that the authentication failed due to an unknown or invalid username.incorrectPassword property may be set to true to indicate that the authentication failed due to an incorrect password for the given username.