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