Introduction to Logon Services

Authentication is usually handled by a Logon Service. This allows Credentials, Roles and Authorizations to be added to a user's session for later use by the application.

A Logon Service contains Fields, Tables and Resources. These can be employed to retrieve information about a user for verifying their authentication and for populating Credentials, Roles and Authorizations.

Fields are used by the Logon Service to store authentication parameters and to determine whether a logon has been successful. Additionally, Logon Services contain Tables that are used to populate the Credentials, Roles and Authorizations stored in the user's session.

When using a Logon Service, two Events are utilised:

Integration, run when a logon call is initiated
On Error, run when an error occurs during the execution of an Integration script

The Integration Event is used to handle the logon request and is responsible for setting up the Credentials, Roles and Authorizations.

To create a Logon Service, right-click in the Entity panel and select New > System Service > Logon Service.

Each Logon Service must be paired with a Logon Service Resource. When you create a Logon Service, a corresponding Logon Service Resource is created automatically.

For more information about the Logon Service see the documentation.

Steps

Create a Logon Service and a Logon Service Resource by right-clicking in the Entities tree and selecting New > System Service > Logon Service. Name the Logon Service myLogonService.

Attach a script to the Integration Event of the Logon Service by selecting the Events tab of the System Service Properties. Name the script LogonIntegration and add the following code:

// Extract the username and password hash from the logon request
var username = fields.PARAM1_VALUE.value;
var passwordHash = services.encryption.generateHash(fields.PARAM2_VALUE.value);

// Logging user information in production is not recommended
log(username + ":" + passwordHash);

// Indicate succesful log in by setting the USERID field value
fields.USERID.value = "dummyUsername";

// !!!!!!!
// In practice, you must authenticate a user before setting the USERID field value
// -------

Attach a script to the On Error Event of the Logon Service by selecting the Events tab of the System Service Properties. Name the script LogonError and add the following code:

// Send a message to the log for debugging
log("Error: an error occurred during Logon");

// Add an error message to the return fields
// So that the logon form can catch and handle it
fields.ERRORCODE.value = "999991";
fields.ERRORDESCRIPTION.value = "Error logging in.";

For an example of how to use this Logon Service, complete the Establishing Successful Login tutorial.

Back to Module Next Page