User authentication

This page describes FX Sales' authentication process and options.

Authentication process

Authentication in FX Sales is handled by a servlet, Caplin KeyMaster, which issues authentication tokens trusted by Caplin Liberator. The KeyMaster servlet is usually hosted on the same Java web application server that serves FX Sales, but it could also be hosted on a separate server. Using a protected servlet as the first point of authentication allows FX Sales and Liberator to integrate easily with the bank’s existing security infrastructure, which may include a single sign-on solution (SSO) and two-factor authentication.

If you want to host FX Sales and the KeyMaster servlet on different hosts, then your J2EE web containers must support Cross Origin Resource Sharing (CORS).

When FX Sales is loaded in a browser, it requests an authentication token from the KeyMaster servlet. Access to the KeyMaster servlet requires authentication. If the user does not have an existing authenticated session, then the initial request will be unsuccessful (HTTP 403 Unauthorised) and FX Sales displays its built-in login page to collect the user’s authentication credentials.

ClientClientWebServerWebServerLiberatorLiberatorRequest KeyMaster tokenHTTP 403LoginLogin successfulRequest KeyMaster tokenKeyMaster tokenLogin with KeyMaster tokenLogin successful. Bidirectional connection established.

If the user already has an authenticated session with the Java web application server, then the initial request by FX Sales for an authenticatoin token from the KeyMaster servlet will be successful. Users will have an existing authenticated session if they reload FX Sales, have FX Sales open in another browser, or, as part of a wider single sign-on solution (SSO), they have already authenticated with another of the bank’s web applications.

ClientClientWebServerWebServerLiberatorLiberatorRequest KeyMaster tokenKeyMaster tokenLogin with KeyMaster tokenLogin successful. Bidirectional connection established.

The built-in login page

FX Sales includes a customisable built-in login page, which FX Sales displays when an unauthenticated client requests a KeyMaster authentication token.

fx sales authentication login page

The built-in login page has the following features:

Password recovery

A link is provided for users to submit a request to reset their passwords. The function to submit the request is specified in the configuration: forgottenPasswordFunction.

Two-factor authentication

If enabled, this feature displays a box for the user to enter a two-factor authentication (2FA) token. The 2FA field is displayed after the user has entered their username and password.

Custom images

The following graphics can be replaced with your own branding images:



Top-left company logo


Product logo


Alternatively, the URLs to the background and logos can be changed in the configuration.

Custom content

Add copyright notices, and links to legal disclaimers and terms and conditions to your login page.

Username validation

Usernames can be validated by a named validator (defined in the react-login-page) or a regular expression. See the usernameFormat property of the CAPLIN.LOGIN configuration object.

Caps-Lock warning

The user is warned if they enter their password with Caps-Lock on.

Configuration reference

The default configuration for the login page is specified in the file default-aspect/src/caplinx/LoginConfig.js, and imported into the default configuration file for FX Sales, default-aspect/src/caplinx/AppConfig.js.

To override the default login page configuration, edit the file default/src/caplinx/ExtendedAppConfig.js

Do not edit the LoginConfig.js and AppConfig.js files. Instead, add configuration overrides to the file default/src/caplinx/ExtendedAppConfig.js

An example override to the login page configuration is shown in the example ExtendedAppConfig.js file below:

'use strict';

var AppConfig = require('caplinx/AppConfig');

 * Customer config overrides that differ from the default ones
 * in {@link module:caplinx/AppConfig} should be placed here.
var ExtendedAppConfig = AppConfig;

// Example: Override the login page's KeyMaster URL
ExtendedAppConfig['CAPLIN.LOGIN']['keyMasterUrl'] = 'servlet/CustomKeyMaster';

module.exports = ExtendedAppConfig;

For the specification of the CAPLIN.LOGIN configuration object, see the entry for CAPLIN.LOGIN in the FX Sales configuration reference.