On this page:

7.8Authentication 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.

7.8.1Method: onAuthenticateSuccess

 

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:

  • Enhancing the user demographics, such as looking up their email address in an external directory
  • Setting the SMART launch context for the session based on external factors
  • Adding to or removing permissions from the user session

Parameters

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

Output

  • Returns an authorization outcome object. This outcome may indicate a successful authorization. It may alternately indicate a failed authorization, in which case no access token will be generated and the client will receive an error.

Example

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;
}

Returning Success

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;
}

Returning Failure

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 – The message property is used to supply a human-readable description of why the authentication failed.
  • Unknown Username – The unknownUsername property may be set to true to indicate that the authentication failed due to an unknown or invalid username.
  • Incorrect Password – The incorrectPassword property may be set to true to indicate that the authentication failed due to an incorrect password for the given username.