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
Complete the steps in the Authentication API guide.
Configure the realm to enable Multi-Factor Authentication Methods.
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:
Customers running the Identity Platform v19.07 must install hotfix version 19.07.01-25+ to use the phone and email link capabilities.
Customers running the Identity Platform v20.06 must install hotfix version 20.06-2+ to use the phone and email link capabilities.
Multi-Factor Methods Profile Properties (e.g., Phone 1, Email 1, etc.) in the Identity Platform Advanced Settings (formerly 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
To check the status of link-to-accept responses, see the GET method /auth/link/{REF_ID} endpoint in the Profile Validation API guide.
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 |
| https://secureauth.company.com/secureauth2/api/v2/users/jsmith/factors |