Authentication

This section describes how to authenticate users using the Auth API.

After a user has enrolled with a device, your application can perform Futurae 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” (also called Zero-Touch authentication for which see further below) the high-level procedure is the following:

  1. Call /user/preauth to check if the user is eligible for Futurae 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. Also for some factors, you can supply a callback URL when invoking /user/auth. Futurae will call this URL with status updates and the result of the authentication attempt.

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 Zero-Touch (SoundProof)

Using the Zero-Touch (also called SoundProof) authentication is slightly more involved than the other authentication factors, as it requires your application to also include and use the SoundProof JS SDK guide, in the login page. This is needed for executing the browser part of the Zero-Touch 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 Zero-Touch 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 Futurae 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 SoundProof JS in the browser.

  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. Alternatively, you can supply a callback URL when invoking /user/auth. Futurae will call this URL with status updates and the result of the authentication attempt.

Authentication Using Zero-Touch (SoundProof) Jingle

In Zero-Touch Jingle (also called 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 Zero-Touch Jingle.

The high-level procedure for Zero-Touch 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 Futurae 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. You have to download the jingle from Futurae to your server and then serve it to the client device from your server. Hence, use the jingle_url to retrieve the jingle on your server and then supply a URL to the client via which it can download the jingle from your server. This is important in order to be able to better handle errors. If the jingle download from Futurae fails (e.g., the Futurae mobile app could not be activated remotely in time), then your server can notify the client device accordingly so that it can prompt the user to manually approve the authentication attempt in the Futurae app (i.e., fallback to Approve).

    Note for conversational interfaces: The jingle has to be played via the Audio Player interface of the device (which allows for high quality audio playback), and not via a SSML response type. For example, in Alexa you have to enable the AudioPlayer interface for your skill and then play the jingle via the AudioPlayer Play directive.

  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. Alternatively, you can supply a callback URL when invoking /user/auth. Futurae will call this URL with status updates and the result of the authentication attempt.

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 Futurae 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 with “approve” or /user/auth with “qr_code” as factor. The response, 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 Futurae 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. Alternatively, you can supply a callback URL when invoking /user/auth. Futurae will call this URL with status updates and the result of the authentication attempt.


Futurae Logo

© 2019 Futurae Technologies AG. All rights reserved.
Crafted in Zurich, CH

support@futurae.com
+41 (0) 44 500 88 26