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.

  4. If you use a load balancer:

    When you use the Push-to-Accept, Symbol-to-Accept, or Link-to-Accept MFA method, you must enable session persistence ("sticky sessions") on the load balancer to maintain state with the Identity Platform. The client applications (Login for Endpoints, RADIUS Server) support cookie-based persistence only. Additionally, only the SecureAuth Java SDK supports cookies.

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