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:
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 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
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.
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

status: The status of user ID provided (found, not_found, invalid, etc.); will always be in response
message: Additional information regarding the status; will always be in response
user_id: The user ID provided; will always be in response, whether successful or not
factors: The list of available multi-factor authentication methods available to the user
type: The type of method (phone, kbq, push, etc.)
id: The SecureAuth Identity Platform Profile Property that is mapped to the directory field containing the information required to conduct the authentication (Phone1, Email2, etc.)
The indexed knowledge-based questions within the Knowledge-based Questions SecureAuth Identity Platform Property (KBQ1, KBQ2, etc.)
A unique identifier provided to SecureAuth Identity Platform by the mobile device during the provisioning process (for OATH and Push)

value: The information contained in the SecureAuth Identity Platform Property / directory field (phone number, email address, device name, etc.)
capabilities: The variations available for the factor that require user selection (phone call, text message, etc.)

Success	Fail / Error
{ "status": "found", "message": "", "user_id": "jsmith", "factors": [ { "type": "phone", "id": "Phone1", "value": "123-456-7890", "capabilities": [ "call" ] }, { "type": "phone", "id": "Phone2", "value": "987-654-3210", "capabilities": [ "sms", "call", "sms_link" ] }, { "type": "email", "id": "Email1", "value": "jsmith@company.com", "capabilities": [ "email", "email_link" }, { "type": "kbq", "id": "KBQ1", "value": "What city were you born in?" }, { "type": "kbq", "id": "KBQ2", "value": "What was your favorite childhood game?" }, { "type": "kbq", "id": "KBQ3", "value": "What was your dream job as a child?" }, { "type": "kbq", "id": "KBQ4", "value": "Who is your personal hero?" }, { "type": "kbq", "id": "KBQ5", "value": "What is the last name of your favorite school teacher?" }, { "type": "kbq", "id": "KBQ6", "value": "What is the name of your favorite childhood pet?" }, { "type": "help_desk", "id": "HelpDesk1", "value": "987-654-3210" }, { "type": "help_desk", "id": "HelpDesk2", "value": "987-654-3211" }, { "type": "push", "id": "8117b62897734d71b48ecdcab19bd437", "value": "HTC One", "biometricTypes": [ "fingerprint", "face" ], "capabilities": [ "push", "push_accept", "push_accept_symbol", "push_accept_biometric" ] }, { "type": "oath", "id": "63c6b390cac04efb8d283828ed29c120", "value": "SecureAuth OTP Mobile App" }, { "type": "pin", "value": "Private PIN" } ], }	{ "status": "not_found", "message": "User Id was not found" } HTTP Status 404 { "status": "invalid_group", "message": "User Id is not associated with a valid group." } HTTP Status 200 { "status": "disabled", "message": "Account is disabled." } HTTP Status 200 { "status": "lock_out", "message": "Account is locked out." } HTTP Status 200 { "status": "password_expired", "message": "Password is expired." } HTTP Status 200 See Server Error information below

Success

Fail / Error

{
  "status": "found",
  "message": "",
  "user_id": "jsmith",
  "factors": [
    {
      "type": "phone",
      "id": "Phone1",
      "value": "123-456-7890",
      "capabilities": [
        "call"
      ]
    },
    {
      "type": "phone",
      "id": "Phone2",
      "value": "987-654-3210",
      "capabilities": [
        "sms",
        "call",
        "sms_link"
      ]
    },
    {
      "type": "email",
      "id": "Email1",
      "value": "jsmith@company.com", 
      "capabilities": [ 
        "email", 
        "email_link"
    },
    {
      "type": "kbq",
      "id": "KBQ1",
      "value": "What city were you born in?"
    },
    {
      "type": "kbq",
      "id": "KBQ2",
      "value": "What was your favorite childhood game?"
    },
    {
      "type": "kbq",
      "id": "KBQ3",
      "value": "What was your dream job as a child?"
    },
    {
      "type": "kbq",
      "id": "KBQ4",
      "value": "Who is your personal hero?"
    },
    {
      "type": "kbq",
      "id": "KBQ5",
      "value": "What is the last name of your favorite school teacher?"
    },
    {
      "type": "kbq",
      "id": "KBQ6",
      "value": "What is the name of your favorite childhood pet?"
    },
    {
      "type": "help_desk",
      "id": "HelpDesk1",
      "value": "987-654-3210"
    },
    {
      "type": "help_desk",
      "id": "HelpDesk2",
      "value": "987-654-3211"
    },

    {
      "type": "push",
      "id": "8117b62897734d71b48ecdcab19bd437",
      "value": "HTC One",
      "biometricTypes": [
        "fingerprint", 
        "face"
      ],
      "capabilities": [
        "push",
        "push_accept",
        "push_accept_symbol",
        "push_accept_biometric"
       ]
     },
    {
      "type": "oath",
      "id": "63c6b390cac04efb8d283828ed29c120",
      "value": "SecureAuth OTP Mobile App"
    },
    {
      "type": "pin",
      "value": "Private PIN"
    }
  ],
}

{
  "status": "not_found",
  "message": "User Id was not found"
}
HTTP Status 404

{
  "status": "invalid_group",
  "message": "User Id is not associated with a valid group."
}
HTTP Status 200

{
  "status": "disabled",
  "message": "Account is disabled."
}
HTTP Status 200

{
  "status": "lock_out",
  "message": "Account is locked out."
}
HTTP Status 200

{
  "status": "password_expired",
  "message": "Password is expired."
}
HTTP Status 200

See Server Error information below

A server error returns the following response:

{
  "status": "server_error",
  "message": "<Exception message describing the issue.>",
}
HTTP Status 500

In this section:

Multi-Factor Authentication API guide

Prerequisites

GET endpoint

Search results