Quick Start

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:

1. Create an Authentication Factor
2. Challenge the Authentication Factor
3. Verify the Challenge

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

• A WorkOS account

• 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.

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

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

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'

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

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.

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

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

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

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('sk_example_123456789');
const response = await workos.mfa.verifyFactor({
  authenticationChallengeId: 'auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5',
  code: '123456',
});

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

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.