Multi-Factor Authentication API guide

Updated October 2, 2020

Use this guide to configure the SecureAuth Authentication API to access user information, including multi-factor authentication methods configured for a profile.

Prerequisites

  1. Complete the steps in the Authentication API guide.

  2. Configure the realm to enable Multi-Factor Authentication Methods.

  3. Link-to-accept

    Capabilities for phone (sms_link) and email (email_link) now enable end users to get a link-to-accept request through email or their phone.

    "Login Request" workflows for phone and email are available for companies that want end users to log in via a link-to-accept request. Ensure the following:

    1. Customers running the Identity Platform v19.07 must install hotfix version 19.07.01-25+ to use the phone and email link capabilities.

    2. Customers running the Identity Platform v20.06 must install hotfix version 20.06-2+ to use the phone and email link capabilities.

    3. Multi-Factor Methods Profile Properties (e.g., Phone 1, Email 1, etc.) in the Identity Platform Classic Experience realm must be accurately mapped to directory attributes to enable multi-factor authentication workflows. The new workflows for link-to-accept include the following:

      • Login Request + One-Time Passcode via Phone Call Only

      • Login Request + One-Time Passcode via SMS Only

      • Login Request + One-Time Passcode via Phone Call and SMS

    4. To check the status of link-to-accept responses, see the GET method /auth/link/{REF_ID} endpoint in the Profile Validation API guide.

GET endpoint

The /users/<username>/factors endpoint uses the GET method to access the end user's profile and respond with the list of available multi-factor authentication methods.

A GET endpoint does not have a body, so JSON parameters are not required.

The factors are returned if you use /api/v2 and the user status in Active Directory matches one of the following:

  • InvalidGroup

  • Disabled

  • Lockout

  • PasswordExpired

  • AccountExpired

HTTP Method

URI

Example

GET

/api/v2/users/<username>/factors

https://secureauth.company.com/secureauth2/api/v2/users/jsmith/factors