beforelogin

note

This article is about the beforelogin UDB event handler.

beforelogin

The beforelogin event may be called from web pages developed in Web Designer and processed by a USoft page engine service.

Event	Applies to	Occurs when
beforelogin	Page objects	Before each login action

This event is triggered internally on the global UdbApplication object, from the login() function of the UdbApplication class (usoft.module.application.js).

Purpose

You can use the beforelogin event to block processing if the event occurs and a given condition is not satisfied.

How to use

Find or create an Event Listener object with Event Type = beforelogin. Event Listeners are in the Web Designer Controls catalog:

Insert the event listener into the Page object. Insert a callClientScript action into the event listener. Use this action's Script property to code the behaviour that you want to see when the event occurs. A typical pattern is to specify the condition under which you want processing to be blocked, to block the process, and to give an error message in an alert box. This pattern looks like this:

if ( *condition-not-satisfied* ) {
  options.success = false;
  alert( *message* );
}

You are implicitly associating the event with an event handler function. This function has an options parameter. For available options, see the Options section at the end of this help topic:

function(*event*, *options*){ ... }

Or you can create the event handler more explicitly by calling $.udb.on().

Options

When the event occurs, the following event handler function is called. You can use this function's options parameter in your event scripting.

function( *event*, *options* )

*event*     ::=  jQuery.Event
*options*   ::=  *event-options*

*event-options*   ::=  {
     success:  *success*,
     options:  *caller-options*
}

*success*  ::=  { [true] | false }

Event contains the run-time details of the triggered event, of the event type stated above.

This syntax means that you can access the success option by scripting:

options.success

and that you can access the caller options by scripting

options.options.*caller-option*

If you set success to false, processing is interrupted. As a result, login will not take place.

Caller-options are the options exposed by the .login() function of the calling page object.

Multi-factor authentication and SSO

The beforelogin event only fires for the initial submission of credentials (user name and password). It does not cover every path by which a user can become authenticated:

• Multi-factor authentication (MFA). When the application prompts for an MFA code and the code is submitted by calling $.udb.login({checkCode: code}), the login() function of the UdbApplication class takes an early-return branch straight to context().ping(user), bypassing the beforelogin trigger entirely. Only the initial credential submission (user name and password) fires beforelogin; the subsequent MFA-code submission does not.

• Single sign-on (SSO). When SSO is configured, authentication happens through a full browser redirect to an external SSO endpoint. On return from that endpoint, the UdbSSO class's internal #checkCurrentUser() function (usoft.module.auth.sso.js) calls UdbApplication.setLoginStatus(true) directly and never calls the UdbApplication.login() function at all. As a result, beforelogin never fires when SSO handles authentication.