Multi-factor Auth
PreviewA composable API for implementing Multi-Factor Authentication (MFA) for basic authentication strategies.
The Multi-Factor Authentication (MFA) API is intended to be a composable, unopinionated set of endpoints that can be integrated into existing application/session management strategies.
The available types of authentication factors are:
totp
- Time-based one time password.sms
- One time password via SMS message.
Note: The MFA API is not intended to be used with the WorkOS SSO product. It's recommended to leverage the MFA features of the Identity Provider that is powering your SSO implementation.
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:
To get the most out of this guide, you'll need:
- A WorkOS account.
Object
Definition
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.
WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application's language.
Node.js
Ruby
Go
Python
PHP
Laravel
.NET
Java
Request an SDK
Don't see an SDK you need? Contact us to request an SDK!
Install the SDK using the command below.
Install the WorkOS SDK
npm install @workos-inc/node
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.
Environment Variables
WORKOS_API_KEY='sk_example_123456789'WORKOS_CLIENT_ID='client_123456789'
Use the totp
type when the user is using a third-party authenticator app such as Google Authenticator or Authy.
Enroll Endpoint
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const response = await workos.mfa.enrollFactor({6 type: 'totp',7 issuer: 'Foo Corp',9});
The provided qr_code
value is a base64 encoded data URI. It can be used to display the QR code in your application for enrollment with an authenticator application.
The secret
is also provided in the response which can be used with some authenticator applications.
Now that we've successfully created an authentication factor, we'll need to save the ID for later use. It's reccomended that you persist the factor ID in your own user model according to your application's needs.
Next we'll initiate tha authentication process for the newly created factor which we'll refer to as a challenge.
Challenge Endpoint
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const response = await workos.mfa.challengeFactor({6 authenticationFactorId: 'auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ',7});
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.
Verify Endpoint
1import WorkOS from '@workos-inc/node';23const workos = new WorkOS('sk_example_123456789');45const response = await workos.mfa.verifyFactor({6 authenticationChallengeId: 'auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5',7 code: '123456',8});
If the challenge is successfully verified valid
will return true
. Otherwise it will return false
and another verification attempt must be made.
Response
{"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.