# User authentication

FX Mobile supports both one-factor (1FA) and multi-factor (MFA) authentication. 

FX Mobile also supports a dual-permissioning system that contains separate sets of permissions for one-factor and multi-factor authenticated users. 

## Overview

FX Mobile supports one-factor authentication and multi-factor authentication. 

The multi-factor authentication system supports numeric one-time passwords (OTP) that are either sent by SMS or generated by hardware key.

The dual-permission system provides users with two access modes: 

* View mode - Read-only access to view trades and monitor live market data for one-factor authenticated users.
* Trade mode - Full access to place trades and orders while monitoring live market data for multi-factor authenticated users. 

Users select which mode they need when they sign in. Users who want to change from view mode to trade mode may upgrade their access by providing a one-time password. This way the user does not need to sign out and re-authenticate in full. 

## Authentication process

FX Mobile provides a flexible authentication solution to integrate with your existing security infrastructure. 

The diagram below shows one such implementation based on the [KeyMaster SignOn Framework](../caplin-platform/keymaster/keymaster-keymaster-signon-framework.md). for FX Mobile using the KeyMaster SignOn Framework. KeyMaster is Caplins single sign on solution for [Liberator](../caplin-platform/liberator/liberator-how-it-works.md).

```plantuml
skinparam BoxPadding 10
actor "FX Mobile" as webapp
box "SignOn Servlet"
  participant "OWASP CSRFGuard" as owaspfilter <<Request Filter>>
  participant "SignOn" as signonservlet <<Servlet>>
endbox
box "OSWAP Guard Servlet"
  participant "OWASP CSRFGuard" as owaspservlet <<Servlet>>
endbox
box "KeyMaster Servlet"
  participant "Authentication" as authfilter <<Request Filter>>
  participant "KeyMaster" as keymasterservlet <<Servlet>>
endbox
box "Liberator"
  participant "Liberator" as liberator
  participant "Permissioning" as pam <<auth module>>
endbox
box "Permissioning Adapters"
  participant "Trade-mode" as trademode <<Adapter>>
  participant "View-mode" as viewmode <<Adapter>>
endbox
box "Bank Systems"
  database "User\nAuthentication" as authentication
  database "User\nAuthorisation" as authorisation
endbox
== Permissioning Adapter start up ==

trademode -> authorisation : Request global permissions
authorisation --> trademode
trademode --> liberator : Broadcast global permissions
viewmode -> authorisation : Request global permissions
authorisation --> viewmode
viewmode --> liberator : Broadcast global permissions


== FX Mobile app opened ==
webapp -> authfilter: Request KeyMaster token
authfilter --> webapp: No live session 
note over keymasterservlet
  The app requests a token as a way of checking if a session already exists. 
  If no session already exists the user is prompted to sign in.
end note 
== FX Mobile user sign in ==
webapp -> signonservlet : GET /parameters
webapp <-- signonservlet
note over owaspfilter
  Return supported encryption
  algorithms, public key,
  and list of MFA modes
end note
webapp -> owaspservlet : Request CSRF token
webapp <-- owaspservlet
webapp -> owaspfilter : POST /authenticate/user
owaspfilter -> signonservlet ++
signonservlet -> authentication : Verify credentials
signonservlet <-- authentication
owaspfilter <-- signonservlet --
webapp <-- owaspfilter
== Connect to Liberator ==

webapp -> authfilter : Request token from KeyMaster
authfilter -> keymasterservlet
keymasterservlet --> webapp
webapp -> liberator ++ : Connection request (with KeyMaster token)
liberator -> pam : Check user
pam -> trademode : Get user permissions
trademode -> authorisation
authorisation --> trademode
trademode -->pam
pam --> liberator
webapp <-- liberator : Connection established
```

### Permissiong Adapter start up

When the Permissiong Adapters start up they query the banks system for global user permissions. 

### FX Mobile app opened 

When the FX Mobile app starts up, it requests a KeyMaster token from the KeyMaster Servlet. The Authentication Filter intercepts the requests to determine if the user is authenticated. If the user s not authenticated an error 403 (forbidden) is returned, and FX Mobile displays the sign in page to the user.  

### FX Mobile user sign in

FX Mobile requests the sign-on parameters from the SignOn Servlet.

The SignOn Servlet returns the supported encryption algorithms, the public key, and a list of multi-factor authentication modes supported. Current supported modes are SMS and token.

FX Mobile then requests for a Cross-Site Request Forgery (CSRF) token. In the diagram above we use OWASP CSRFGuard as an example of a CSRF token provider. For more information on OWASP CSRFGuard, see [OWASP CSRFGuard Project](https://owasp.org/www-project-csrfguard/). The CSRF token is returned to the FX Mobile app and stored.

When the user enters their credentials, FX Mobile sends an authentication request to the SignOn Servlet. The request passes through the OWASP CSRFGuard filter, which checks if the request has a valid CSRF token. 

The SignOn Servlet checks that the user’s credentials match the user credentials held in the bank’s user authentication system. If the users' credentials match the credentials held by the bank, authentication is complete. The user is now signed in to the FX Mobile app.

### Connect to Liberator

FX Mobile requests a KeyMaster token from the KeyMaster Servlet. The request is intercepted by the Authentication Filter to check the user is authenticated. The KeyMaster Servlet creates and returns an authentication token to FX Mobile. 

FX Mobile sends a connection request to Liberator and presents the KeyMaster token. Liberator checks that both the age of the token and the signature on the token is valid. If the token is valid, the connection to Liberator is established.

---

**See also:**

* [KeyMaster](../caplin-platform/keymaster/index.md)