Quick Start

Enroll new authentication factors and build challenge verification.

What you’ll build

In this guide, we’ll walk you through the process of enrolling new authentication factors for a user, and the challenge/verification process for existing authentication factors.

This guide will show you how to:

Create an Authentication Factor
Challenge the Authentication Factor
Verify the Challenge

Before getting started

To get the most out of this guide, you’ll need:

A WorkOS account

API Object Definitions

Authentication Factor. A factor of authentication that can be used in conjunction with a primary factor to provide multiple factors of authentication.
Authentication Challenge. A request for an Authentication Factor to be verified.

1. Create an Authentication Factor

We’ll first need to enroll a new Authentication Factor.

Install the SDK using the command below.

npm install @workos-inc/node

You can also download the workos-node source code from GitHub.

Set environment variables

As a best practice, your WorkOS API key should be kept secret and set as an environment variable on process start. The SDK is able to read the key automatically if you store it in an environment variable named WORKOS_API_KEY; otherwise, you will need to set it manually. The Client ID should also be set dynamically based on the release environment.

WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

Enroll the Authentication Factor

Using Time-based One Time Password (TOTP)

Use the totp type when the user is using a third-party authenticator app such as Google Authenticator or Authy.

import WorkOS from '@workos-inc/node';
const workos = new WorkOS('secretKey');
const response = await workos.mfa.enrollFactor({
  type: 'totp',
  issuer: 'Foo Corp',
  user: 'alan.turing@foo-corp.com',
});

The response returns a qr_code and a secret. The qr_code value is a base64 encoded data URI that is used to display the QR code in your application for enrollment with an authenticator application.

The secret can be entered into some authenticator applications in place of scanning a QR code.

Using SMS

Use the sms type when the user wants to receive one time passwords as SMS messages to their mobile device.

Phone number must be valid. An error will be returned for malformed or invalid phone numbers.

import WorkOS from '@workos-inc/node';
const workos = new WorkOS('secretKey');
const response = await workos.mfa.enrollFactor({
  type: 'sms',
  phoneNumber: '+15005550006',
});

Now that we've successfully created an authentication factor, we’ll need to save the ID for later use. It's recommended that you persist the factor ID in your own user model according to your application's needs.

2. Challenge the Authentication Factor

Next we’ll initiate the authentication process for the newly created factor which we’ll refer to as a challenge.

Create Authentication Challenge

import WorkOS from '@workos-inc/node';
const workos = new WorkOS('secretKey');
const response = await workos.mfa.challengeFactor({
  authenticationFactorId: 'auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ',
});

Sending Custom SMS Message

When challenging an SMS authentication factor, you can pass an optional sms_template to customize the SMS message that is sent to the end user. Use the {{code}} token to inject the one time password into the message.

import WorkOS from '@workos-inc/node';
const workos = new WorkOS('secretKey');
const enrollResponse = await workos.mfa.challengeFactor({
  authenticationFactorId: 'auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ',
  smsTemplate: 'Your FooCorp is {{code}}.',
});

Now that we've successfully challenged the authentication factor, we’ll need to save the challenge ID for the last step, challenge verification.

3. Verify the Challenge

The last step in the authentication process is to verify the one time password provided by the end-user.

import WorkOS from '@workos-inc/node';
const workos = new WorkOS('secretKey');
const response = await workos.mfa.verifyFactor({
  authenticationChallengeId: 'auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5',
  code: '123456',
});

Verification Response

If the challenge is successfully verified valid will return true. Otherwise it will return false and another verification attempt must be made.

{
  "challenge": {
    "object": "authentication_challenge",
    "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
    "created_at": "2022-02-15T15:26:53.274Z",
    "updated_at": "2022-02-15T15:26:53.274Z",
    "expires_at": "2022-02-15T15:36:53.279Z",
    "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ"
  },
  "valid": true
}

Already Verified Error

If a challenge was already successfully verified, it cannot be used a second time. If there is need for further verification is need in your application, simply create a new challenge.

{
  "code": "authentication_challenge_previously_verified",
  "message": "The authentication challenge 'auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5' has already been verified."
}

Expired Error

For SMS authentication factors, challenges are only available for verification for 10 minutes. After that they are expired and cannot be verified.

{
  "code": "authentication_challenge_expired",
  "message": "The authentication challenge 'auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5' has expired."
}

We've now successfully verified an end-user's authentication factor. This authentication factor can now be used as a second factor of authentication in your application's existing authentication strategy.

The ID of the authentication factor should be persisted in your application for future authentication challenges.