Time-based One-time Password (TOTP)

Definition and Default Configuration

The Time-Based One-Time Password (TOTP) factor works with any authenticator app such as Google Authenticator, Authy, Aegis, etc. Once seeded, the Authenticator App generate password that are only valid for a short period of time (30 seconds by default) and only valid once.

An account can enroll multiple TOTP 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 counter resets to 0 on each successful login.

TOTPs are case-sensitive by default.

User Interface (UI) Example

Below is a sample screenshot to give an idea of a potential login / registration page asking for a Time-Based One-Time Password (TOTP).

Login with Authenticator App (TOTP) on the Hosted Login Page (Quasr).

On a login page, the Time-Based One-Time Password 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.

Signup with a TOTP factor

The signup with a Time-Based One-Time Password (TOTP) happens in two steps (two API calls), the setup and the initial verification:

Setup (Step 1 of the signup process)

Signup with Authenticator App (TOTP) on the Hosted Login Page (Quasr).

To set up a Time-Based One-Time Password, a label (label parameter) can optionally be provided.

Signup with a TOTP factor (first signup-step)

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

200: OK Successful signup (with access token)

{
  "result": "PENDING",
  "feedback": {
    "cause": "ENROLLMENT_PENDING",
    "enrollment_id": "<enrollment_id>",
    "initialization_url": "<otp_auth_uri>", // turns this into QR code
    "secret": "<secret>", // manual setup
    "expires_at": "ISO timestamp",
    "regex": "<regex>"
  }
}

200: OK Successful signup (with session token)

{
  "result": "PENDING",
  "feedback": {
    "cause": "ENROLLMENT_PENDING",
    "enrollment_id": "<enrollment_id>",
    "initialization_url": "<otp_auth_uri>", // turn this into QR code
    "secret": "<secret>", // manual setup
    "expires_at": "ISO timestamp",
    "regex": "<regex>"
  },
  "session_token": "<session_token>",
  "account_id": "<account_id>",
  "session_score": <session_score>,
  "session_exp": <session_expiration> // epoch in seconds (not ms)
}

After the enrollment request is made, the factor enrollment is in a PENDING state.

The enrollment request will return feedback in the response, which is to be used for an initial validation (see below) in order to progress the enrollment from PENDING to ENABLED state.

The feedback contains a

• secret: the setup key, in case the end-user cannot or does not want to scan a QR code

• initialization_url: the URI in case you want to generate a QR Code by yourself

• enrollment id: the id of the just created enrollment

Use this feedback information to provide the secret and/or QR code to the end-user in order for them to scan the QR code or manually setting up the TOTP in their authenticator app.

Sample Response:

{
  "result": "PENDING",
  "feedback": {
    "cause": "ENROLLMENT_PENDING",
    "enrollment_id": "d61c3081-c96d-4319-a1a9-65c58727e25f",
    "initialization_url": "otpauth://totp/Quasr:e6f2215c-869e-41d3-92dc-c63ed49eb6bf?secret=PNCQA3R5KUWFS532&period=30&digits=6&algorithm=SHA1&issuer=Quasr",
    "secret": "PNCQA3R5KUWFS532",
    "expires_at": "2023-07-22T11:50:15.000Z",
    "regex": "[0-9]{6}"
  }
}

Verification (Step 2 of the signup process)

To verify a Time-Based One-Time Password (TOTP) factor, the TOTP (input parameter) is provided.

After the first successful verification, the enrollment status will switch from PENDING to ENABLED.

Verifying a TOTP factor (second signup-step)

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

Headers

Name	Type	Description
Authorization*	String	Session or Access Token

Request Body

Name	Type	Description
input*	String	TOTP from authenticator app
id*	String	Enrollment ID

200: OK Failed authentication

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

200: OK Successful authentication (with access token)

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

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)
}

Login with a TOTP factor

Google Authenticator with various Quasr enrollments

To login with a Time-Based One-Time Password (TOTP) factor, the TOTP (input parameter) is provided together with the factor enrollment id.

Login with a TOTP factor

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

Headers

Name	Type	Description
Authorization*	String	Session or Access Token

Request Body

Name	Type	Description
id*	String	Enrollment ID
input*	String	TOTP from authenticator app

200: OK Failed authentication

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

200: OK Successful authentication (with access token)

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

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>
}

Factor Creation & Configuration

A Time-Based One-Time Password Factor is already available for all newly created tenants by default, however, if you want to add additional password factors, you can do so via Tenant Administration UI or Admin API.

The following API sample calls create an Time-Based One-Time Password factor labelled "Another TOTP" with a score of 2.

The Time-Based One-Time Password Factor allows for the following parameters and config options:

Parameter	Value Options	Default	Required
subtype	"totp"
label	<string>	"Authenticator App"
status	"ENABLED" | "DISABLED"	"DISABLED"
score	<positive int>	1
config.public_signup	true | false	false
config.require_validation_for_enablement	true | false	true
config.issuer	<string>	"Quasr"

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

GraphQL Example

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

// GraphQL Variables (Sample)
{
  "input": {
    "subtype": "totp",
    "label": "Another TOTP",
    "status": "ENABLED",
    "score": 2
  }
}

// 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": "totp",
      "label": "Another TOTP",
      "status": "ENABLED",
      "score": 2
    }
  }
});

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);
});

Recommended TOTP Apps

Below is a list of TOTP apps that we can recommend (Quasr has no affiliation with these vendors).

• Aegis (Open Source)
• FreeOTP (Open Source)
• Authy
• Google Authenticator: Android - iOS