Enrollment

Before being able to use authenticate a user in your application using Futurae, you must first enroll the user and one or more of his devices in Futurae. This section describes how to enroll (aka activate or register) users and their devices in Futurae using the Auth API.

There are different types of devices, offering different authentication technologies and capabilities and depending on the type of device the enrollment process may vary.

The following cases are discussed below:

• Mobile App Enrollment
• FIDO Authenticator Enrollment
• Hardware Token Enrollment
• Phone Number Enrollment

Mobile App Enrollment

Before being able to use authentication for a user of your application, you must first enroll the user and his mobile device on the Futurae server. Each user can have multiple enrolled devices, but he must have at least one enrolled device in order to be able to use authentication. For most authentication factors, such as Approve, the Futurae mobile app (or your app which has the Futurae SDK integrated) has to be installed on the user’s device and paired with that user’s account.

The following flowchart illustrates the basic steps for performing enrollment using a Mobile app:

In summary, you have to take the following steps:

1. Instruct the user to install the Futurae mobile app (or your mobile app which has the Futurae SDK integrated) on his device, in case he does not already have the application installed.

2. Call /user/enroll (in particular either Enroll New User with Mobile Device or Enroll New Mobile Device for Existing User) and display to the user the activation QR code. The QR code can be retrieved and displayed using two alternatives:

   1. Through the activation_qrcode_data_uri response key which contains the PNG image of the QR code inlined in data URI format. This is the recommended way.

   2. If for some reason you cannot make use of the data URI option, you can alternatively use the URL contained in the activation_qrcode_url response key to retrieve the PNG image of the QR code.

   The user uses the camera of his device in order to scan the QR via the Futurae app.

   Alternatively, if the user is performing the enrollment process from the mobile device on which he installed the app, he can tap on the link provided by the activation_code_uri 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.

3. If you supplied a success_callback_url in /user/enroll you will automatically be notified via the callback once the enrollment completes successfully. Alternatively, you can poll the progress of the enrollment with the /user/enroll_status endpoint.

FIDO Authenticator Enrollment

Before being able to use FIDO2/WebAuthn authentication for a user of your application via Futurae, you must first enroll the user and a FIDO2/U2F compatible authenticator for that user.

The process is somewhat similar to what was described in the Mobile App Enrollment section, with a few differences as explained below (in particular, there is no need to instruct the user to install an app of his phone, as he will be using a FIDO authenticator):

1. Call /user/enroll (in particular either Enroll New User with FIDO Device or Enroll New FIDO Device for Existing User). An activation code will be returned in two variatons, the default, named activation_code, and the short, named activation_code_short (you need to set the short_code input param to true for the short form to be returned).

2. On the client-side, using the WebAuthnJS SDK, create a new FuturaeWebAuthn object, init() it and then invoke enroll() on it, passing the activation code using one of the two variatons. Which variatons you use depends on which of the two approaches below you wish to implement:

   • Implicit: Pass the activation_code (default variation) to enroll() in the background. The user will be able to activate his FIDO authenticator, being completely unaware of the activation code. This approach assumes that the enrollment process is sufficiently authenticated and/or attacker-free.
   • Explicit: Get the short variation of the activation code, activation_code_short, by supplying the short_code input param as true. Deliver the short activation code to the user using an out-of-band channel. When the user is about to activate his FIDO device, ask the user to supply the code and pass the supplied value to enroll(). This approach increases the security of the FIDO registration step, and is useful when the activation process is not sufficiently authenticated or the risk that the attacker might be able to hijack the activation process is not acceptable.

3. If you supplied a success_callback_url in /user/enroll you will automatically be notified via the callback once the enrollment completes successfully. Alternatively, you can poll the progress of the enrollment with the /user/enroll_status endpoint.

Hardware Token Enrollment

Before you are able to use a Hardware Token for authenticating a user in Futurae, you need to assign the token to the user. Overall, the process is straightforward and the assignment operation can be completed with a simple API call. Refer to Enroll New User with Hardware Token and Enroll New Hardware Token for Existing User on how to achieve this.

Phone Number Enrollment

In order to use SMS passcodes as an 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 (in particular either Enroll New User with SMS Device or Enroll New SMS Device for Existing User) 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).