One-Time Password (OTP)

Definition and Default Configuration

The One-Time Password (OTP) is a randomly generated password that is only valid for a short amount of time and can only be used once.

An account can enroll multiple OTP factors if they wish to.

The default maximum failed attempts before the factor gets temporarily disabled is 5. The factor will auto-unlock after 300 seconds (5 minutes). The default maximum pending attempts (so the start of the flow) before the factor get temporarily disabled is 5. Both counters reset to 0 on each successful login. After auto-unlock only the pending counter gets reset to 3.

The default expiration time is 10 minutes.

The default regex is [A-Z0-9]{6} (so 6 alphanumeric characters and only capitalized).

OTPs are non-case-sensitive by default.

OTPs are stored hashed (Argon2id).

If you read the section about Quasr not holding any customer data (or PII), you may now wonder so how does Quasr deliver one-time passcodes (OTPs) to customers in case it doesn't have relevant data like the email. Well the solution is simple, when Quasr wants to deliver an OTP to your user it will use an extension. This extension is to be setup by you and could point to an API on your end. It can then receive the OTP as well as some useful info (such as account ID) you could use to relay to your API. It can use the Quasr account ID to retrieve any required personal data from your Customer Data Solution and next deliver the OTP to the end user (through any communication channel you choose).

This "webhook" approach is already popular in the industry as it allows you to plug in any channel for your users. Often customers re-use an existing email or SMS gateway, but the approach also gives flexibility in integrating whatever communication channel your users prefer.

An extension works in similar way as the webhook or endpoint it points to, consuming information about the One-Time-Factor signup or login process and processing it in order to deliver the OTP to the customer. The difference is that the code extension is custom code (Node.js) running on the Quasr platform, so that there is no need to host the code for the handling logic on your end, as it is the case when using webhook.

User Interface (UI) Example

Below is a sample screenshot to give an idea of a potential login / registration page asking for a OTP factor. On a login page, the OTP input field is usually represented by a single-line password field or a set of single-digit input fields, which optionally also allows for copy/pasting values into it.

Login with email OTP on the Hosted Login Page (Quasr).

Signup with One-Time Password (OTP)

To enroll an OTP factor, a label (label parameter) can optionally be provided.

Step 1: Creating the OTP enrollment:

Signup with an OTP factor (step 1 of signup process)

POST https://{tenant_id}.api.quasr.io/factors/signup

Headers

Name	Type	Description
Authorization	String	Session or Access Token

Request Body

Name	Type	Description
label	String	Label
id*	String	Factor ID
input	String	Identifier for the delivery channel, i.e. email or phone number

200: OK Successful signup

{
  "result": "PENDING",
  "feedback": {
    "cause": "ENROLLMENT_PENDING",
    "enrollment_id": "<enrollment id>"
  }
}

After the signup request is made, the factor enrollment is in a PENDING state. The response return an enrollment id, which is to be used in the next step.

This request triggers the OTP delivery - the OTP is sent as an event, which an extension can listen for, along with the expiration, the account id, enrollment - see Extension for the detailed payload.

OTP Verification (step 2 of signup process)

POST https://{tenant_id}.api.quasr.io/factors/signup

Headers

Name	Type	Description
Authorization	String	Session or Access Token

Request Body

Name	Type	Description
id*	String	Enrollment ID
input*	String	OTP (One-Time Password)

200: OK Failed authentication

{ 
  "result": "FAILED",
  "feedback": {
    "cause": "INCORRECT_INPUT"
  }
}

200: OK Successful authentication (with session token)

{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment_id>"
  },
  "session_token": "<session_token>",
  "account_id": "<account_id>",
  "session_score": <session_score>,
  "session_exp": <session_expiration> // epoch in seconds (not ms)
}

200: OK Successful authentication (with access token)

{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment_id>"
  }
}

After successful verification, the OTP enrollment changes its status from PENDING to ENABLED and can now be used by the account as a login factor.

Login with a One-Time Password (OTP)

In order to validate an OTP, the user first needs to receive one. Here, they make below validation request without any OTP (input parameter) provided. This will trigger the generation and event of the OTP.

Email OTP example (Quasr)

Once the user received the OTP, they would then make the very same call but with providing the received OTP as input parameter.

Validating an OTP factor

POST https://{tenant_id}.api.quasr.io/factors/login

Request Body

Name	Type	Description
input	String	OTP (One-Time Password) If no input is provided, the request will trigger the OTP delivery through the configured webhook
id*	String	Factor or Enrollment ID

200: OK Failed authentication

{
  "result": "FAILED",
  "feedback": {
    "cause": "INCORRECT_INPUT",
  }
}

200: OK Successful validation (with access token)

{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment_id>"
  }
}

200: OK Successful validation (with session token)

{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment_id>"
  },
  "session_token": "<session_token>",
  "account_id": "<account_id>",
  "session_score": <session_score>,
  "session_exp": <session_expiration> // epoch in seconds (not ms)
}

Factor Creation & Configuration

OTP Factors can be added via Tenant Administration UI or Admin API.

The OTP Factor allows for the following parameters and config options:

Parameter	Value Options	Default	Required
subtype	"otp"
label	<string>	"One-Time Password"
status	"ENABLED" | "DISABLED"	"DISABLED"
score	<positive int>	1
config.regex	regex
config.unique	true | false	true
config. case_sensitive	true | false	false
config. public_signup	true | false	false
config.require_validation_for_enablement	true | false	true
config.otp	regex	"[A-Z0-9]{6}"
config.capture_input	true | false	false

The Quasr Access Token used in the Authorization header in the examples below must contain the scope https://api.quasr.io/scopes/admin in order to be authorized. See API Authorization

The following API sample calls create an OTP factor labelled "OTP" with a score of 2.

GraphQL Example

// GraphQL Query (Sample)
mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}

// GraphQL Variables (Sample)
{
  "input": {
    "subtype": "otp",
    "label": "OTP",
    "status": "ENABLED",
    "score": 2,
    "regex": "^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$" // phone
  }
}

// Response (Sample)
{
    "data": {
        "createFactor": {
            "id": "8bde5565-7027-4232-8db8-3f3ca1acaeac"
        }
    }
}

Node.js Example

var axios = require('axios');
var data = JSON.stringify({
  query: `mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}`,
  variables: {
    "input": {
      "subtype": "otp",
      "label": "OTP",
      "status": "ENABLED",
      "score": 2,
      "regex": "^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$" // phone
    }
  }
});

var config = {
  method: 'post',
  url: 'https://{tenant_id}.api.quasr.io/graphql',
  headers: { 
    'Authorization': 'Bearer {access_token}', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});