Skip to main content

Mutual Authentication

Mutual authentication is when two sides of a communication channel (e.g. SMS, phone call, online chat, etc) verify each other's identity, instead of only one side verifying the other.

Authentication flow​

Mutual authentication flow

Creating a session​

1. In your organization's dashboard, click on the Auth Sessions button​

2. Select a template from the list or start from scratch​

Mutual authentication templates

3.1 From template​

Mutual authentication from template

  • Fill in an optional subject with non-identifying information
  • Fill in the Expected value with an identifying piece of information.
tip

We highly recommend asking for information that relates to the identity within the communication channel being used, this protects against man-in-the-middle attacks

  • Change the expiration duration if needed (must be between 30 secs and 15 mins / 900 secs)
note

The identifying information is always hashed with salt before being sent to our servers, learn more here

3.2 From scratch​

Mutual authentication from scratch

  • Chose a field type (Text, Number or Date)
  • Chose a field name, it must be straighforward and relate to what identifying information you will ask from the user
  • You can add up to three fields, but we recommend using only one to make the user experience more fluid
  • You can save the template for future use, it will subsequently be selectable from the previous dropdown
  • Fill out the other fields like you would from a template

4. Start session​

Once you click Start session, an ephemeral one-use session will be created and the countdown will start immediately. You are presented with the following modal:

Mutual authentication modal

  • The Prefill session checkbox lets you add a query string to the URL that is picked up when the session is opened, automatically filling the first field and submitting if there is only one field. This removes some privacy as the identifying information is present in the URL but speeds up the authentication process as there is no action expected from the receiver besides asking for the secret code.
  • The Reveal passcode button is to be clicked when the receiver asks you for the secret code. To prevent man-in-the-middle attacks the secret can only be viewed after the recipient has viewed it in their session.
  • The Recreate button is a helper for when the session expired or is about to expire and the receiver has not authenticated yet.

5. History​

Everytime you create a session, a history record about it is saved to allow some traceabilty, even after the session has expired or is deleted.

note

None of the authentication field values are persisted or sent to our servers, only metadata as seen in the columns below.

Mutual authentication history

6. What the end user sees​

The mutual authentication interface is displayed below the organization profile.

warning

The URL can only be opened once (i.e. it is single-use), subsequent requests or page refreshes will display an invalid session. This is by design to protect against man-in-the-middle attacks.

Empty user fields​

The receiver of the link is prompted to input identifying information unique to them and the given session:

Mutual authentication client side empty

Filled user fields​

Mutual auth client manually filled

Valid user fields​

note

If the shared link is prefilled, this step is immediately displayed.

Mutual auth field is valid

At this stage the secret code is revealed and the receiver must ask the sender for it.

If both passcodes match, both parties can be considered authenticated.

Invalid user fields​

If the digest of the field values does not match what is expected for the given session id or the session has expired:

Mutual auth client is invalid