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

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” and “mobile_auth” (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 order to query the status and eventually retrieve the result of this particular authentication attempt, via the /user/auth_status endpoint.

Authentication From Mobile Devices

When a user is logging in from a browser or native application on mobile device that has the Futurae mobile app installed and enrolled for that particular user, then the MobileAuth factor can be used to strongly and conveniently authenticate the user. 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 using MobileAuth is the following:

  1. Register the set of accepted Service URL and App ID patterns (see further below for explanation of the concepts). You can do this by calling the relevant Auth API endpoints. This is an one-off operation that has to happen before performing MobileAuth authentication attempts.

  2. When starting an authentication attempt, 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).

  3. Call /user/auth to start the MobileAuth authentication process (factor parameter set to “mobile_auth”) on a selected device that offers the “mobile_auth” capability. This endpoint will return a session_id that identifies the newly created authentication session and a session_token which needs to be used on the client-side where the login is taking place (browser or native app) and passed to the respective Futurae mobile auth SDK.

  4. On the client side (browser or native app), use the respective SDK functionality in order to initiate a “mobile_auth” session. You will need to pass the session_token which was received via the /user/auth endpoint. Moreover, register for the available callback functions. Each callback will be triggered when a particular event occurs during the “mobile_auth” 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).

    • For more information regarding the iOS mobile auth SDK see the respective documentation.
    • Android mobile auth SDK: coming soon.
    • JavaScript mobile auth SDK: coming soon.
  5. Use the session_id (retrieved by /user/auth) in order order to query the status and eventually retrieve the result of this particular authentication attempt, via the /user/auth_status endpoint.

Service URL and App ID Concepts

For MobileAuth to work properly and securely, you need to register a set of URLs and App IDs which the Futurae mobile app can use and verify during a MobileAuth session in order to securely communicate with your website (when using a mobile browser) or native app from which the login originates. A correct configuration of the Service URLs and App IDs is crucial for the proper functioning and security of the MobileAuth factor, so the concept is explained in more details in the following section.

Service URL

The Service URL is used during the MobileAuth protocol execution to verify the target to perform the callback to the calling app or website. To verify the target of a callback, it must match at least one Service URL pattern.

Include all URL Schemes that your native apps will register on the mobile platforms (e.g. democlient://) and URLs of the login pages (relevant for mobile browser logins, e.g. https://demo.com/login) for which you want to enable MobileAuth.

App IDs

The App ID is used during the MobileAuth protocol execution to verify the origin of a URL Scheme call. To verify the origin, it must match at least one App ID pattern.

Include all App IDs of the native apps (e.g. com.democlient.app) for which you want to enable MobileAuth.

Pattern Matching

To validate a Service URL or App ID pattern, the actual values are matched based on Go’s filepath matching and may include * wildcards. For this reason, e.g. https://* matches https://futurae.com, but not https://futurae.com/.

For security reasons, each pattern should be as restrictive as possible. Invalid patterns are rejected, see the respective Golang doc to explore how the matching algorithm works.

Examples

iOS

A native iOS app has the Bundle ID com.democlient.app, and there also exist beta and development versions of the app with Bundle IDs com.democlient.beta.rc and com.democlient.beta.dev. All apps have registered the URL Scheme democlient://.

The following configuration is recommended:

{
  "service_urls": ["democlient://"],
  "app_ids": ["com.democlient.app", "com.democlient.beta.*"]
}

Android

A native Android app has the package name com.democlient.app, and there also exist beta and development versions of the app with the package names com.democlient.beta.rc and com.democlient.beta.dev. All apps have registered an intent-filter with the scheme democlient.

The following configuration is recommended:

{
  "service_urls": ["democlient://"],
  "app_ids": ["com.democlient.app", "com.democlient.beta.*"]
}

Website

The login page of a website is located at https://service.com/login, but since the website is localized using a sub-domain, there are other login pages at https://en.service.com/login, https://de.service.com/login etc.

The following configuration is recommended:

{
  "service_urls": ["https://service.com/login", "https://*.service.com/login"],
  "app_ids": [""]
}



© Copyright 2017 Futurae Technologies AG.

Generated by aglio on 31 Oct 2017