Skip to main content

Authentication API overview

In order to leverage Arculix by SecureAuth to perform Multi-Factor Authentication for existing applications, a set of APIs are provided. The application (or "relying party") authenticates the user internally and then delegates the Smart MFA process to Arculix. This is a three phase process which can be implemented in several different ways to meet the application's requirements.

  • Authentication Request - Details of the user, application, and context are submitted to Arculix to be processed by the risk engine and policy orchestration engine in order to generate a result and an LOA score

  • MFA - The user is required to perform an out of band verification step using Push, SMS, TOTP etc. This step may be bypassed if the Authentication Request is automatically approved by the policy engine

  • Result - The relying party is notified that the MFA phase has been completed and requests the result from Arculix, then allows or blocks user access to the application appropriately

Glossary

  • LOA - A Level of Assurance, as defined by the ISO/IEC 29115 Standard, describes the degree of confidence in the processes leading up to and including an authentication. It quantifies assurance that the user claiming a particular identity is the user to which that identity was assigned. LOA is a number between 0 to 4, with 0 being minimal confidence in the asserted identity of the user and LOA level of 4 showing a very high confidence in asserted identity of the user.

  • OTP - A One-Time Passcode can be used to approve an authentication request. Users can have the OTP sent to them via SMS, voice call, or email.

  • Out-of-band - User authentication over a network or channel separate from the primary network or channel; used in multi-factor authentication.

  • Relying Party - The relying party is an organization or application which relies on Arculix for doing multi-factor authentication.

  • Request - The request method, URL, and parameters

    • All request parameters are mandatory unless explicitly marked as optional

    • Each request parameter has a defined field, type, and description

  • Response - All the possible responses are listed for each method. Only one of them is issued per request.

    • All responses are in JSON format.

  • Status - The HTTP status code of the response.

  • TOTP - A Time-based One-Time Password is a six-digit passcode that changes every 30 seconds. The Arculix TOTP seed can be added to the Arculix Mobile app or any other compatible authenticator in Arculix.

Prerequisites

  • An application created in Arculix to correspond with the relying party application; this assigns a UID and secret which are required for most API calls

  • For the Previous User Authentication API: Users of the relying party application must be registered with Arculix.

    For the New User Authentication API: Integration with Active Directory is required to perform just-in-time user provisioning.

MFA Overview

There are several different ways for a relying party to implement Arculix's Smart MFA; here is one example of the steps in a typical flow.

  1. The user identifies themselves to the relying party; this can be via username and password login or passwordless options such as QR scan login.

  2. The relying party initiates an authentication request with Arculix, including the user identifier and authentication context such as the Device Browser Fingerprint.

  3. Arculix responds to the authentication request with the result of analysis by the risk engine and policy orchestration, including whether the user must perform MFA

  4. The relying party either redirects the user to the Arculix MFA page or provides their own authentication screen, where the user can select an out of band MFA method and provide a verification code or approve a push notification

  5. Arculix notifies the relying party that the authentication request has been resolved and the relying party queries Arculix for the result

  6. The relying party acts based on the authentication result: if it is approved, the user is allowed access to the application but if it is expired or rejected, the user's access is denied

API calls and endpoints

To see the calls and endpoints for the updated API, see New User Authentication API. Note that the calls for this version of the API are only supported for organizations that are integrated with Active Directory.

In this section: