Profile Validation API guide

Updated October 2, 2019

Use this guide to configure the SecureAuth Authentication API to validate end user information and to generate one-time passcodes (OTPs), push-to-accept, and link-to-accept requests for end user authentication.

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.

  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.

Endpoints

Use the /auth endpoints to validate information associated with a user account, and to generate and deliver OTPs.

The POST method validates end user information (e.g., username, password, KBAs, tokens, etc.) and generates OTPs for authentication.

  • For ad hoc OTP delivery, the supported "type" values are call, sms, and email.

  • The send ad hoc OTP API allows an impromptu OTP to be dispatched to a valid phone number or email address that is not currently stored in the directory (i.e., unregistered).

Note

Refer to Authentication API: Send Ad hoc OTP without Existing User Profile for specific configuration steps when using ad hoc OTP delivery to users who are not registered in the directory.

The GET method checks the status of push-to-accept and link-to-accept responses.

When a push-to-accept request is made, the corresponding response contains a Reference ID, which is then appended to the /auth endpoint to continuously check whether the login request is accepted, denied, pending, or other.

When a link-to-accept request is made, the corresponding response contains a Reference ID, which is then appended to the /auth/link endpoint that waits 2 minutes for a response before expiring.

POST /auth

The POST /auth method validates the end user response.

HTTP Method

URI

Example

POST

/api/v2/auth

https://secureauth.company.com/secureauth2/api/v2/auth

GET /auth/{REF_ID}

Use the GET /auth method to access the end user's profile and generate a response.

HTTP Method

URI

Example

GET

/api/v1/auth/{REF_ID}

https://secureauth.company.com/secureauth2/api/v1/auth/f50ab2d7-178f-4421-b3ae-9f5634fa54ef