Back to top

Futurae Auth API Guidelines

The Futurae Auth API can be used in order to add two-factor authentication and transaction signing to your website or application, or integrate any of the offered authentication factors into your existing authentication platform.

Here you will find some generic guidelines on how to make use of the Auth API, as well as some more specific instructions for using the SoundProof authentication factor.

In order to be able to use the Auth API you will need to get your Service ID, Service Auth API key and Service hostname. Please refer to the Auth API reference documentation for a detailed reference of the available HTTP endpoints, and on the structure and format of the each individual HTTP request and response.

Requirements

All the authentication factors offered by Futurae, except SMS, require the installation and usage of the Futurae mobile app. The Futurae mobile app is available on the following platforms:

  • Android (minimum required version: Jelly Bean 4.1.x – API Level 16)

  • iOS (minimum required version: iOS 9)

Moreover SoundProof authentication is supported on the following browsers:

  • Google Chrome

  • Microsoft Edge

  • Apple Safari (from version 11)

  • Mozilla Firefox

  • Opera

Auth API Usage Overview

The Auth API features two main categories: Endpoints for enrolling and managing users, and endpoints for performing two-factor authentication and transaction signing for enrolled users.

Enrollment with the Futurae Mobile App

Before being able to use secondary authentication for a user of your application, you must first enroll the user and his second-factor device on the Futurae server. Each user can have multiple enrolled second-factor devices, but he must have at least one enrolled device in order to be able to use secondary authentication. For most authentication factors, such as SoundProof and Approve, the Futurae mobile app has to be installed on the user’s device and paired with that user’s account.

To enroll a user and his device:

  1. Instruct the user to install the Futurae mobile app on his device, in case he does not already have the application installed.
  1. Call /user/enroll and display to the user the QR code which can be retrieved by the URL contained in the activation_qrcode_url response key. The user uses the camera of his device in order to scan the QR via the Futurae app. Alternatively, if the user is enrolling from his second-factor device, he can tap on the link provided by the activation_code response key, which will automatically invoke the Futurae mobile app. In both cases, and if the user’s device has internet connectivity, the device will be enrolled and associated with the particular user.
  1. You can poll the progress of the enrollment with the /user/enroll_status endpoint.

Enrollment with a Phone Number

In order to use SMS passcodes as a second authentication factor, a user first needs to enroll the phone number of his device. In this case the enrollment process is slightly different, as it does not involve the Futurae mobile app:

  1. Call /user/enroll and supply the phone_number parameter.

  2. Use the device_id contained in the response (which is associated with the above supplied phone number) to send a verification SMS code to the registered phone number using /user/sms_activation. In order to verify the code supplied by the user, the same endpoint can be used (refer to the API doc for details on the format of the request). If the code is correct then the particular phone number is considered enrolled with this user and can be used for sending SMS passcodes (“sms” factor in /user/auth).

Authentication

After a user has enrolled with a device, your application can perform secondary authentication for that user, using any of the available factors, and depending on the capabilities of the user’s devices. The details of the process depend on the selected factor, nevertheless for all factors except “soundproof” (for which see further below) the high-level procedure is the following:

  1. Call /user/preauth to check if the user is eligible for secondary authentication, as well as retrieve his enrolled devices and the capabilities of each device (the capabilities of a device determine which factors can be used with that device).
  1. Call /user/auth to start the secondary authentication process, with a selected factor on a selected user device.
  1. For some factors /user/auth will return immediately, providing a session_id. Your application can use the session_id in order to query the status and eventually retrieve the result of this particular authentication attempt, via the /user/auth_status endpoint. For the “passcode” factor, /user/auth will return immediately, providing the result of the passcode verification. Finally for some other factors, there is an option to supply the async parameter, which when set to false, will cause the endpoint to run synchronously and return a response when the authentication process has completed.

We stress again that there are some slight variations on this generic flow, depending on the particular authentication factor. Please refer to the documentation of the /user/auth and /user/auth_status endpoints for more details. Also, refer to the next section for more details on SoundProof authentication (“soundproof” factor) in particular.

Authentication Using SoundProof

Using the SoundProof authentication is slightly more involved than the other authentication factors, as it requires your application to also include and use the SoundProof JavaScript library, in the login page. This is needed for executing the browser part of the SoundProof protocol. In short, it involves recording audio for a few seconds, and sending the recording to the user’s device over the Internet).

The high-level procedure for the SoundProof factor is the following:

  1. Call /user/preauth to check if the user is eligible for secondary authentication, as well as retrieve his enrolled devices and the capabilities of each device (the capabilities of a device determine which factors can be used with that device).
  1. Call /user/auth to start the SoundProof authentication process (factor paremeter set to “soundproof”) on a selected device that offers the “soundproof” capability. This endpoint will return a session_id that identifies the newly created SoundProof authentication session and a session_token which needs to be used when invoking the SoundProof JavaScript library on the browser side.
  1. On the browser side, create a new SoundProof object and invoke start() on it, passing the session_token which was received via the /user/auth endpoint. Moreover, when creating the SoundProof object, you can pass in a number of callback functions. Each callback will be triggered when a particular event occurs during the SoundProof process, thus giving you the opportunity to get notified about various important events on the client side. Nevertheless, you can only receive the final result via the backend Auth API (see next step).
  1. Use the session_id (retrieved by /user/auth) in order to query the status and eventually retrieve the result of this particular authentication attempt, via the /user/auth_status endpoint.

Mobile Only Authentication (Single Device)

When a user is logging in from a mobile browser or native application on a mobile device that has the Futurae mobile app installed and enrolled for that particular user, then the user can be strongly and conveniently authenticated using the mobile only (or mobile auth) approach. In this particular case, the user is logging in from his trusted device (i.e., one that has the Futurae mobile app installed and enrolled), and in order to strongly authenticate the user we just need to ensure that the login indeed originates from a trusted device.

The general flow for performing mobile only authentication using Futurae is the following:

  1. Call /user/preauth to check if the user is eligible for secondary authentication, as well as retrieve his enrolled devices and the capabilities of each device (the capabilities of a device determine which factors can be used with that device).
  1. Call /user/auth as usual, using “approve” or “qr_code” as factor. The response from /user/auth, among other things, will contain a mobile_auth_uri attribute.
  1. Pass the mobile_auth_uri to your client app (mobile browser or native app). Create a button with the supplied URI as action, and prompt the user to tap on it in case he is on his mobile device with the Futurae mobile app installed.
  1. The user taps the button which triggers the invocation of the Futurae mobile app. The Futurae mobile app will perform the secondary authentication. After the authentication is completed and depending on the situation, the user will either be automatically switched back to the client app or will be prompted to do a manual switch.
  1. In the meantime, use the session_id (retrieved by /user/auth) in order to query the status and eventually retrieve the result of this particular authentication attempt, via the /user/auth_status endpoint.



© Copyright 2018 Futurae Technologies AG.

Generated by aglio on 19 Feb 2018