# User authentication

This page describes Caplin FX Corporate’s authentication process and options.

## Authentication process

Authentication in FX Corporate is handled by a servlet, [Caplin KeyMaster](../caplin-platform/keymaster/index.md), which issues authentication tokens trusted by [Caplin Liberator](../caplin-platform/liberator/index.md). The KeyMaster servlet is usually hosted on the same Java web application server that serves FX Corporate, but it could also be hosted on a separate server. Using a protected servlet as the first point of authentication allows FX Corporate 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.

**📌 NOTE**\
If you want to host FX Corporate and the KeyMaster servlet on different hosts, then your J2EE web containers must support [Cross Origin Resource Sharing (CORS)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing).

When FX Corporate 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 Corporate displays its built-in login page to collect the user’s authentication credentials.

```plantuml
Client -> WebAppServer: Request KeyMaster token
WebAppServer --> Client: HTTP 403
Client -> WebAppServer: Login
WebAppServer --> Client: Login successful
Client -> WebAppServer: Request KeyMaster token
WebAppServer --> Client: KeyMaster token
|||
Client -> Liberator: Login with KeyMaster token
Liberator --> Client: Login successful. Bidirectional connection established.
```

If the user already has an authenticated session with the Java web application server, then the initial request by FX Corporate for an authentication token from the KeyMaster servlet will be successful. Users will have an existing authenticated session if they reload FX Corporate, have FX Corporate 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.

```plantuml
Client -> WebAppServer: Request KeyMaster token
WebAppServer --> Client: KeyMaster token
|||
Client -> Liberator: Login with KeyMaster token
Liberator --> Client: Login successful. Bidirectional connection established.
```

## The built-in login page

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

![fx_corporate_login_2](../images/fx_corporate_login_2.png)

The built-in login page has the following features:

* [Password recovery](#password-recovery)
* [Two-factor authentication](#two-factor-authentication)
* [Custom images](#custom-images)
* [Custom content](#custom-content)
* [Username validation](#username-validation)
* [Caps-Lock warning](#caps-lock-warning)

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

* **Background**\
 `/default-aspect/unbundled-resources/images/login_screen_bg.jpg`
* **Top-left company logo**\
 `/default-aspect/unbundled-resources/images/login_screen_company_logo.svg`
* **Product logo**\
 `/default-aspect/unbundled-resources/images/login_screen_product_logo.png`

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 Corporate, `default-aspect/src/caplinx/AppConfig.js`.

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

**❗ IMPORTANT**\
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:

```js
'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](fxcorp-fx-corporate-configuration.md#caplin-login) in the [FX Corporate configuration](fxcorp-fx-corporate-configuration.md) reference.