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 high level guidelines on how to make use of the Auth API, including instructions for performing Zero-Touch authentication using SoundProof.

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.

Futurae Authentication Suite

Futurae offers a portfolio of authentication factors, which leverage the user’s phone or other mobile devices as software tokens which the user proves possession of during authentication. This is realized by having the user install the Futurae mobile app on his mobile device and enrolling it with his account (except SMS which relies on the user’s mobile phone number). All the available factors can be integrated and used via the Futurae Auth API. The following tables summarize the currently offered factors and their properties.

Description
Approve One-Touch authentication using a push notification which is sent to the user’s mobile device.
Mobile Auth Single device authentication (i.e., the user is authenticating from a mobile device with an enrolled Futurae mobile app).
QR Code One-Touch authentication using QR code scanning (also known as PhotoTAN).
SMS Authentication via a one-time code which is received via SMS (also known as mTAN).
SoundProof Zero-Touch authentication by transparently verifying proximity of the user’s mobile device and the device on which the authentication takes place. Soundproof leverages background ambient sounds, coupled with near-ultrasound emission in order to verify proximity of the two devices.
SoundProof Jingle Zero-Touch authentication, similar to SoundProof, but with an audible jingle being played during authentication. Ideal for authentication on conversational interfaces, such as Amazon Alexa.
TOTP Authentication via a time-based one-time code which is retrieved by the Futurae mobile app.
User interaction Transaction signing Backend-only integration Mobile app Internet connectivity on mobile device Specify device*
Approve Yes Yes Yes Yes Yes Yes
Mobile Auth Yes Yes Yes Yes Yes No
QR Code Yes Yes Yes Yes Yes No
SMS Yes Yes Yes No No** Yes
SoundProof No No No Yes Yes Yes
SoundProof Jingle No No Yes Yes Yes Yes
TOTP Yes No Yes Yes No No

* The device which is going to be used for a particular authentication attempt needs to be specified, in case the user has multiple enrolled devices (“auto” option is available, which automatically uses the user’s most recently enrolled device).

** SMS does not require Internet connectivity on the phone, but it still requires the ability to receive SMS messages.

Requirements

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:

The authentication factors offered by Futurae, except SoundProof, are supported on all browsers.

SoundProof authentication, in particular, 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 secondary authentication and transaction signing for enrolled users.

Enrollment with the Futurae Mobile App

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

The following flowchart illustrates the basic steps for performing an enrollment:

In summary:

  1. Instruct the user to install the Futurae mobile app (or your mobile app which has the Futurae SDK integrated) on his device, in case he does not already have the application installed.

  2. 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 performing the enrollment process from the mobile device on which he installed the app, 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.

  3. If you supplied a success_callback_url in /user/enroll you will automatically be notified via the callback once the enrollment completes successfully. Alternatively, 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 following flowchart illustrates the basic steps for performing a authentication:

The details of the process depend on the selected factor, nevertheless for all factors except “soundproof” and “soundproof_jingle” (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).

  2. Call /user/auth to start the authentication process with a selected factor. For factors where it’s applicable, you may need to specify the user device (or “auto” to automatically use the most recently enrolled one). Also where applicable, use the extra_info parameter in order to supply information about the particular authentication attempt(e.g., the user’s approximate location, IP address and browser). This will appear on the user’s screen, along with the option to approve or reject the authentication attempt.

  3. 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 illustrated in the flowchart of the previous section and also summarized below:

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

  2. Call /user/auth to start the SoundProof authentication process (factor parameter 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.

  3. 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).

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

Authentication Using SoundProof Jingle

In SoundProof Jingle, the proximity of the client device on which the authentication takes place and the user’s mobile device is based on an audible jingle that the client device has to play during authentication. The client device can be any device capable of playing audio through speakers. Conversational interfaces, such as Amazon Alexa, are typical examples and ideal use cases for SoundProof Jingle.

The high-level procedure for SoundProof Jingle is illustrated in the flowchart of the previous section and also summarized below:

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

  2. Call /user/auth to start the SoundProof Jingle authentication process (factor parameter set to “soundproof_jingle”) on a selected device that offers the “soundproof_jingle” capability. This endpoint will return a session_id that identifies the newly created SoundProof Jingle authentication session and a jingle_url which can be used on the client side to retrieve the jingle that has to be played. If the jingle is to be played at a later time after it is retrieved then the playback_offset parameter has to be set accordingly upon calling this endpoint.

  3. On client side, use the jingle_url to download and play the appropriate jingle for this authentication attempt. For it to work properly, it is assumed that the jingle will be played as soon as it is retrieved, with no delays. This URL is safe to be passed directly to the client. For example, the conversational interface can directly download and play the jingle using this URL.

  4. 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).

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

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

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

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

Transaction Authentication

Futurae offers the ability to protect sensitive actions, which an authenticated user performs in your application, such as performing a financial transaction, or updating sensitive information in his profile. This is called transaction authentication (or transaction signing).

The following flowchart illustrates the basic steps for performing transaction authentication:

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

  2. Call /user/auth/transaction to start the transaction authentication process with a selected factor. Use the extra_info parameter in order to supply information about the action which the user has to approve. This will appear on the user’s screen, along with the option to confirm or reject the transaction.

  3. For some factors /user/auth/transaction 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. 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/transaction and /user/auth_status endpoints for more details.




© Copyright 2018 Futurae Technologies AG.

Generated by aglio on 16 Aug 2018