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:
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:
Modify Futurae users
Modify User endpoints may be used to modify some attributes of an existing Futurae User:
Deactivate Futurae users
The Deactivate User endpoint permanently changes the user
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:
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.:
id "xyz" in your application corresponds to the Futurae User with
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:
usernamevalue has to be unique within a given Futurae Service.
usernamevalue 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
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
statusof a newly created user is
- The user
enabledas long as the user has at least one enrolled device.
- If the last enrolled device of a user is unenrolled, the user
- A Futurae User whose
bypass, will bypass the Futurae authentication, and any authentication attempt for this user will automatically return
allow. A user’s
statusmay be set to
bypassusing the previously mentioned Modify User endpoints, or alternatively at Futurae Admin as described here.
- Only users with the
bypassare eligible for authentication using Futurae.
locked_outuser means that any Futurae authentication attempt for this user will return
deny. A user's
statusmay be automatically set to
locked_outif the user reaches the number of consecutive failed authentication attempts defined by the value of the user
max_attemptsattribute (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_outusing 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
statusis permanently updated to
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.
A Futurae user device is uniquely identified by the
device_id field value.
Device display name
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:
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:
The equivalent of the Auth API Enroll New Mobile Device for Existing User for the Admin API is the Enroll New Mobile App endpoint:
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:
The list of user’s devices may be obtained by calling the following Admin API endpoint:
The Modify User Device endpoints provides an interface to modify the device’s
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: