Add multifactor authentication

Note: This document is written for Classic Engine. If you’re using Identity Engine, you can find multiple guides and use cases to help you add MFA to your apps: for example, explore our Embedded SDK use cases documentation. See Identify your Okta solution (opens new window) to determine your Okta version.

This guide explains how to implement multifactor authentication (MFA) and provides an example of how to use the Okta Factors API to add an additional factor for a user.

---

Learning outcomes

• Set up your Okta org to use MFA.
• Enroll, activate, and test a factor. The examples shown are Google Authenticator and SMS.

What you need

• Okta Developer Edition organization (opens new window)
• Postman configured to make API requests to your Okta Developer Edition org
• The Users API and Factors API Postman Collections
• An API token (created in your Okta org)

---

About MFA

MFA is quickly becoming the standard for app developers and organizations to add an extra layer of security to their apps. Okta gives you the flexibility to deploy our built-in factors or integrate with existing tokens. Native factors include SMS and the Okta Verify app for iOS and Android. Integrations include Google Authenticator, RSA SecurID, Symantec VIP, and Duo Security.

Note: How you actually make the HTTPS calls depends on the programming language and web framework that your app uses. Okta has helper libraries that make it easy to add support for Okta to your app in an idiomatic way.

Set up your Okta org for MFA

First, enable support for MFA in the Admin Console of your Okta org.

Enable MFA in your Okta org

Enable MFA from the Admin Console of your Okta org before you can use it with the Okta API.

1. In the Admin Console, go to Security > Authenticators.
2. Click Add Authenticator, and then click Add on the Google Authenticator tile.
3. Click Add to add the service.

See MFA (opens new window) and Sign-on Policies (opens new window) for more information.

Test the Postman setup

Next, make sure that your Postman setup is configured correctly:

1. In Postman, select the Collections tab on the left.
2. Select the Users (Okta API) collection and then the List Users folder.
3. Scroll to the List Users folder and select the List Users request template. The request appears on the right.
4. Click Send. A successful request results in an HTTP status code of 200 and a JSON payload response with the Users associated with your org.

Note: If you don't already have Postman set up, follow these instructions to set up Postman to work with Okta. There’s also a dedicated page with all of our Postman Collections.

Create a test user

Create a user in Okta to test your MFA setup:

1. Open the Users (Okta API) collection in Postman and then the Create User folder.
2. Select the Create User without Credentials request template. The request template appears on the right.
3. Select the Body tab and enter the first name, last name, and email address for your new user. Use the email for the login property.
4. Click Send. A successful request results in an HTTP status code of 200 and a JSON payload response.
5. Save the value of the User id that is returned in the response.

Enroll a factor

You’re now ready to enroll an additional factor for the user that you created.

Using the ID for the User that you created earlier, add a Google Authenticator factor for that User:

1. In Postman, open the Factors (Okta API) collection, and then the Factor Lifecycle Operations collection.
2. Select the Enroll Google Authenticator Factor request template. The request appears on the right.
3. In the request URL, replace the {userId} variable with the user ID that you saved in Create a test user.
4. Click Send to add the Google Authenticator Factor for your user. A successful request results in an HTTP status code of 200 and a JSON payload response.
5. Save the Factor ID value (id) from the response.
6. In the \_embedded object located at the bottom of the response, locate the _links object and then the href value of the qrcode property.
7. Copy this URL and open it in a new tab of your browser. A QR code appears. We use this QR code in the next step.

Activate the factor

After enrolling a factor for the Okta user, the next step is for the user to activate their factor.

1. Open Google Authenticator on your phone.
2. Tap the plus sign + in the app.
3. Select the Scan barcode option.
4. Scan the QR Code on the browser tab that you opened previously.
5. Switch to Postman and from the Factor Lifecycle Operations collection, select the POST Activate TOTP Factor request template.
6. Replace the {userId} and {factorId} variables with the User ID and Factor ID values that you copied previously.
7. Select the Body tab and, in the JSON body of the request, replace the passCode value with the passcode shown in the Google Authenticator app.
8. Click Send. A successful request results in an HTTP status code of 200 and a JSON payload response.

Verify the factor

Now that the factor has been enrolled and activated, you can verify that the factor works as intended.

1. Open the Factors (Okta API) collection, and then the Factor Verification Operations collection.

2. Select the POST Verify TOTP Factor request template.

3. Replace the {userId} and {factorId} variables with the User ID and Factor ID values that you copied previously.

4. Select the Body tab, and in the JSON body of the request, replace the passCode value with the passcode shown in the Google Authenticator app.

5. Click Send. A successful verification of a token results in an HTTP status code of 200 with a JSON payload that contains the key factorResult with the value of SUCCESS.

   Unsuccessful verification attempts result in an HTTP status code of 403 with a JSON payload that contains the key errorCode.

Next steps

At this point, you should understand how to use the Okta API to add MFA to an existing app. You can learn more about using the Okta MFA API using the following resources:

• The Reference overview for the Okta API (opens new window)
• The API documentation for the Okta Factors API (opens new window)
• The API documentation for the Okta Authentication API