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 an authentication:

auth_api_authentication_flow

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 and smart speakers, such as Amazon Alexa, are typical examples and ideal use cases for Zero-Touch Jingle.

The high-level procedure for implementing Zero-Touch Jingle for a smart speaker application is illustrated in the flowchart below, followed by a more detailed explanation:

auth_api_zerotouch_jingle_flow

As depicted in the image above, Zero-Touch jingle can be used to authenticate a user before processing a sensitive request. For example the user might ask:

“What is my account balance?"

Before processing this security-sensitive command, your application backend checks whether the user is sufficiently authenticated. If not, you prompt to authenticate:

“You are not authorized to access this information. Please authenticate first."

The user then asks the smart speaker:

“Authenticate me."

At this moment, your backend application initiates a Zero-Touch (SoundProof) jingle authentication for this user, which includes the following steps:

  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 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. Read through steps 3 and 4 below to understand how to use playback_offset correctly.

  3. You have to download the jingle from Futurae to your application backend and then serve it to the smart speaker from your server. Hence, use the jingle_url to retrieve the jingle on your server and then supply a URL to the smart speaker 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).

  4. Assuming that your backend downloaded the jingle from Futurae successfully, you then need to prepare the response to be sent to the smart speaker. For example, assuming that this is an Alexa skill, the response can be:

    “Checking if your phone is nearby to authenticate you. Please ask alexa to resume, after the jingle… [jingle plays at this moment]…"\

    You need to measure, approximately, how much time it passes from the moment your backend successfully downloaded the jingle from Futurae until the moment the jingle starts to play on the smart speaker (after the initial spoken words, if any, like in the example above). This is the duration you need to supply in the playback_offset parameter in step 2.

  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.

  6. If the authentication was successful, your backend can mark the user as authenticated.

After the jingle finishes playing the user can ask the smart speaker to proceed with answering the security-sensitive command. If Zero-Touch jingle succeeded, then your backend should authorize the command. If it didn't succeed, and you are still waiting for an answer from Futurae, it means that authentication attempt is still on and has fell back to the One-Touch method. You can prompt the user accordingly:

“I was not able to verify that your phone is nearby. Please open the Futurae app in your phone to approve the authentication request."

Once the user approves the login, Futurae will report the authentication success to your backend, which can now mark the user as authenticated.

Mobile Only Authentication (Single Device)

When a user is logging in via a mobile browser or native application that exists 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 his trusted device.

Let's assume that the user is attempting to log in on a mobile application, let's just call it main app, on his trusted device. Let's also assume that the application is using Future authentication. From a user's perspective, mobile only authentication works as follows:

  1. Initially the user is in the main app. When Futurae authentication takes place the main app will either automatically switch to the Futurae app, or present the user with a button, which when the user taps on it, it will switch to the Futurae app.

  2. The user is now in the Futurae app, where he is asked to approve/reject the authentication request.

  3. Once the user approves/rejects the authentication request, he is automatically transferred back to the main app. Assuming that the user successfully approved the authentication attempt, the main app logs the user in.

In the above description there are two app switch actions happening:

  • Switch from main app to Futurae app (either automatically or by the user tapping on a button), so that the user can approve the authentication attempt.
  • Switch back from the Futurae app to the main app (automatically) once authentication is completed, so that the user can continue using the main app.

On iOS both switch actions happen via URI scheme calls. On Android the main-to-futurae app switch happens via a URI scheme call, but the futurae-to-main app switch happens implicitly via the Android's back stack mechanism.

The URI used for the main-to-futurae app switch is called mobile_auth_uri and it is provided by Futurae to your application via the Auth API. The URI used (on iOS only) for the futurae-to-main app switch is called mobile_auth_redirect_uri, and should be provided by your application to Futurae via the Auth API.

The flow below explains how to use the Auth API in order to realize mobile only authentication:

  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. Pass the mobile_auth_redirect_uri as in input parameter to the request. The response, among other things, will contain the mobile_auth_uri attribute.

  3. Pass the mobile_auth_uri to the main app (page in 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. Alternatively, the main app can automatically call the URI to switch to the Futurae mobile app.

  4. Once the Futurae mobile app is triggered, it will ask the user to confirm the authentication request. After the authentication is completed, the Futurae mobile app will call the mobile_auth_redirect_uri in order to switch back to the main app (only applicable to iOS, in Android the Futurae app activity will finish and the back stack will pop the main app to the foreground).

  5. Once the main app is active in the foreground, it should check with the backend about the result of the authentication attempt and act accordingly. In the meantime, in the backend 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.