This article will give a detailed explanation about the concepts of users and devices, within the Futurae context. It is intended to provide a clear understanding on how these two entities are related to each other.

About the Futurae User

A Futurae User represents a user registered in the Futurae Backend, which is mapped to an actual user in your application. Users utilizing the Futurae Authentication will need to be registered with the Futurae backend.

Futurae provides multiple endpoints to manage Futurae Users, utilizing the Auth and Admin APIs. Although some functionalities may be found in both APIs, the Auth API focuses on authentication and user self-service management flows, while the Admin API offers additional user and device management capabilities within a Futurae Service, from a back office management point of view.

 

Create Futurae users

Futurae users can be created using the Auth or Admin API Enroll Users endpoints, as described in the following documentation:

https://www.futurae.com/docs/api/auth/#enroll-users-and-devices

https://www.futurae.com/docs/api/admin/#enroll-new-user

 

The aforementioned endpoints provide several enrollment options, depending on whether you wish to enroll a new user and device or a device for an existing user. The supported device types (i.e. Hardware Token, mobile phones etc.) are listed here.

 

Details of a Futurae User may be accessed by calling the Get User Information endpoints:

https://www.futurae.com/docs/api/auth/#get-user-information

https://www.futurae.com/docs/api/admin/#get-user-information

 

Modify Futurae users

Modify User endpoints may be used to modify some attributes of an existing Futurae User:

https://www.futurae.com/docs/api/auth/#modify-user

https://www.futurae.com/docs/api/admin/#modify-user

 

Deactivate Futurae users

The Deactivate User endpoint permanently changes the user status to archived, removes any enrolled devices, and also prevents the user from enrolling new devices, resulting in the user becoming unable to authenticate using Futurae.

The Deactivate User endpoint is only available through the Admin API:

https://www.futurae.com/docs/api/admin/#deactivate-user

 

Futurae User attributes

You may find the list of attributes which compose the Futurae User resource at https://www.futurae.com/docs/api/admin/#user. However in this article we will cover only the more relevant ones.

 

Futurae User identifiers

The Futurae User is composed of a user_id and a username, which are used to uniquely identify the user. The user_id is automatically generated by Futurae, whereas the username can be used to submit existing values when calling the Enroll User endpoint. 

By specifying the username you may use this attribute as an identifier to map your users to the respective Futurae User, based on this attribute’s value, i.e.:

User with id "xyz" in your application corresponds to the Futurae User with username "xyz"

 

Using the user id from your application is only an example however you may choose to use any other identifier field from your user model to map to the Futurae user's username. The only requirements are:

• The username value has to be unique within a given Futurae Service.
• The username value follows the input restrictions specified here.

Note that in order to avoid any issues, any value changes on the application side will need to be synchronized with the Futurae Backend. Please refer to the section “Modify Futurae User” of this article.

 

Futurae User display name

The user display_name is an optional field that when set, may be displayed to the user in the authenticator app.

 

Futurae User status

One of the most relevant attributes of the Futurae User resource is status. The importance of this mutable attribute lies in the fact that it states whether a given user is eligible for authenticating using Futurae at a given point in time. A complete description of each possible status is provided in the User Status documentation.

 

The bellow diagram illustrates the possible changes between the different Futurae User status:

 

A few remarks on the transitions between the different Futurae User status:

• The status of a newly created user is disabled.
• The user status is enabled as long as the user has at least one enrolled device.
• If the last enrolled device of a user is unenrolled, the user status returns to disabled.
• A Futurae User whose status is bypass, will bypass the Futurae authentication, and any authentication attempt for this user will automatically return allow. A user’s status may be set to bypass using the previously mentioned Modify User endpoints, or alternatively at Futurae Admin as described here.
• Only users with the status enabled or bypass are eligible for authentication using Futurae.
• A locked_out user means that any Futurae authentication attempt for this user will return deny. A user's status may be automatically set to locked_out if the user reaches the number of consecutive failed authentication attempts defined by the value of the user max_attempts attribute (see https://www.futurae.com/docs/api/admin/#user), or if the limit of ten incorrect attempts to verify the SMS device activation code is exceeded. Moreover, a user may be locked_out using the previously mentioned Modify User endpoints, or alternatively at Futurae Admin.
• When a user is archived, this can be done by calling the Deactivate User endpoint , all the user’s enrolled devices are unenrolled, and the user's status is permanently updated to archived.

 

Devices

The Device resource represents the Futurae User authenticator device, used to perform authentication using Futurae. The different types of authenticator devices are described here.

As stated earlier in this article, whether the user has enrolled device(s), impacts the Futurae User status and consequently dictates if the user is in a condition to authenticate using Futurae.

 

Futurae Device attributes

A complete description of the Futurae device resource may be found at https://www.futurae.com/docs/api/admin/#user, while below we mention the two most relevant attributes.

 

Device ID

A Futurae user device is uniquely identified by the device_id field value. 

 

Device display name

The device display_name is a human friendly name used to identify the device, which may be used for instance in a prompt for the user to easily identify the concerned device.

By default the device's model name is used as display_name, nevertheless, this can be changed through the API (see "Modify Device" below), such that the user can be given the opportunity to set their own mnemonic name for each of their enrolled devices.

 

Enroll Device for new Futurae User

A Device may be enrolled without an existing Futurae user, in this case a new user is created and the user data is returned together with the device activation data (activation codes, and activation QR code data) as result of the same API call, if applicable. For instance, the Enroll New User with Mobile Device endpoints create a new Futurae User with a mobile device:

https://www.futurae.com/docs/api/auth/#enroll-new-user-with-mobile-device

https://www.futurae.com/docs/api/admin/#enroll-new-user-with-mobile-app

 

Enroll Device for existing Futurae User

It is also possible to enroll a new device for an existing Futurae User, such as described in the Enroll New Mobile Device for Existing User section of the API documentation:

https://www.futurae.com/docs/api/auth/#enroll-new-mobile-device-for-existing-user

 

The equivalent of the Auth API Enroll New Mobile Device for Existing User for the Admin API is the Enroll New Mobile App endpoint:

https://www.futurae.com/docs/api/admin/#enroll-new-mobile-app

 

A single user may have multiple activated devices. In this case your application may decide to allow the user to choose which device to use to authenticate using Futurae, by specifying the device_id when calling the authentication endpoint.

 

The Auth API Get User Information endpoints returns the Futurae User data, including the list of the user’s enrolled devices:

https://www.futurae.com/docs/api/auth/#get-user-information

 

The list of user’s devices may be obtained by calling the following Admin API endpoint:

https://www.futurae.com/docs/api/admin/#get-user-device-information

 

Modify Device

The Modify User Device endpoints provides an interface to modify the device’s display_name:

https://www.futurae.com/docs/api/auth/#modify-user-device

https://www.futurae.com/docs/api/admin/#modify-device

 

Unenroll Device

Once unenrolled, a device status is updated to archived. If the user has no other devices enrolled, the user status is updated to disabled, meaning that the user will have to enroll a new device before being able to authenticate.

The following endpoints may be used to unenroll a user device:

https://www.futurae.com/docs/api/auth/#unenroll-user-device

https://www.futurae.com/docs/api/admin/#unenroll-device

 

A user device may be automatically unenrolled by the Futurae SDK (version 2.x.x) due to security reasons, after 5 successive SDK PIN verification failures. More information about the Futurae SDK can be found on the respective SDK guides:

https://www.futurae.com/docs/guide/futurae-sdks/mobile-sdk-android/

https://www.futurae.com/docs/guide/futurae-sdks/mobile-sdk-ios/