Trusted Session Binding offers an additional layer of security to user enrollment and account recovery processes.
In this article, we are describing how to implement Trusted Session Binding.
What is Trusted Session Binding?
Trusted Session Binding is designed to further enhance protecting access to user enrollment and account recovery processes. This feature compels users to undergo additional authentication steps, as required and implemented by the customer backend, before the SDK can execute critical flows for binding a new device, such as enrollments or account recovery. By doing so, it further secures the process with a multi-layered authentication approach and ensures a direct, secure link between the user's actions and the session in which they are conducted.
How does it work?
The main purpose of TSB is to allow the customer backend application to control under which conditions the mobile app can run certain SDK-initiated actions, such as enrollment or account recovery.
For example, if an activation code is sent to the end user via a letter, the customer backend might require the entry of username/password in order to check that this user is entitled to use this activation code.
TSB flows for both enrollment and account recovery follow the same principle. At first, TSB needs to be enabled via Auth or Admin APIs for the scope of a particular enrollment or device account recovery. Then, before the actual enrollment or account recovery flow happens, the customer backend runs a custom verification process to check that the user is entitled to run the flow, at the end of which they request a Futurae TSB jwt
token and share it with the app. Finally, the app can proceed to the actual Futurae flow, including the TSB token in the request. This way, it is ensured that the app frontend flow is successfully “bound” to the custom authorization flow under control of the app backend.
We include the flow diagrams for Enrollment and Account Recovery in the next sections.
SDK requirements
Mobile iOS SDK: v3.1.8 or beyond
Mobile Android SDK: v3.0.5 or beyond
Implementation of Enrollment with Trusted Session Binding
1. [API] Enabling TSB
1.1. Validate that a user is entitled to enroll into Futurae.
1.2. Create a new enrollment with enrollment_flow_binding_enabled
flag set to true
.
1.3. Share the activation code/URI received from Futurae with the user.
2. Custom user verification
2.1. Validate that the user of your mobile app is entitled to enroll with the provided activation code. This step may be optional in your custom flow if the initial User verification from Step 1.1 happened on the same device within a reasonable delay, for instance, if the user is being enrolled directly following an online KYC verification on their mobile. However, in general, this check is needed to ensure that even if the activation code, e.g., delivered to the end user as a QR code letter, gets stolen, it cannot be used to enroll a MFA device for the legitimate user without going through the extra user verification steps. For instance, the custom verification may involve username/password verification with the customer backend application after scanning a hardcopy enrollment QR code.
3. [Auth API] Requesting a TSB token
3.1. Request a TSB token for the enrollment activation code. In a successful scenario, Futurae Auth API replies with 200 OK
and a response payload containing the TSB token.
4. [Futurae SDK] Using the TSB token: Enrollment
4.1. Enroll the device with the TSB token as parameter of the SDK enrollment request.
- On iOS, pass the TSB token as the
bindingToken
parameter to theenroll
method. - On Android, pass the TSB token as the
EnrollmentParams.flowBindingToken
parameter to the FuturaeenrollAccount
method.
4.2. Finally, handle the SDK enrollment response and display the result accordingly to the user.
Enrollment flow with Trusted Session Binding
List of endpoints that support enabling Trusted Session Binding for enrollment
Enabling TSB for enrollment can be done either when creating a new enrollment or by modifying an already existing enrollment
-
New enrollments (as in diagram above)
Enrollment with TSB can be enabled for mobile authenticators and FIDO devices, by providing the parameter"enrollment_flow_binding_enabled": true
, through the following endpoints:
Auth API:
Enroll New User with Mobile Device
Enroll New Mobile Device for Existing User
Enroll New User with FIDO Device
Enroll New FIDO Device for Existing User
Admin API:
Enroll New User with Mobile App
Enroll New User with FIDO Device
Enroll New Device
-
Existing enrollments
Alternatively it is possible to modify an existing enrollment in order to enable TSB:
Modify Enrollment
Implementation of Account Recovery with Trusted Session Binding
On a fresh app installation, the SDK is able to identify if account migration is possible and return the accounts which can be migrated. If there are devices available for migration for which trusted session binding has been enabled, the app has to follow the custom protocol with the app backend to retrieve a TSB token to proceed with the migration.
1. [API] Enabling TSB
1.1. Create a new enrollment with account_recovery_flow_binding_enabled
flag set to true
for new devices. For existing devices that have already been enrolled with this flag set to false
, modify the flag for this device. (See List of endpoints that support enabling Trusted Session Binding for account recovery section below)
2. [Futurae mobile SDK] Query migration options
2.1. Query migration options and retrieve the device IDs of the migratable accounts, which constitute the scope of the account recovery. The diagram below shows an example of an SDK instance where only one account X is available for migration.
We refer to SDK Accounts/Devices interchangeably in the diagram and following text, since a device ID uniquely defines a migratable SDK account.
- On iOS, call
getMigratableAccounts()
, and retrieve the device IDs. - On Android, call
getMigratableAccounts()
, and retrieve the device IDs.
3. Custom user verification
3.1. Validate that the user of your mobile app is entitled to migrate each of the accounts defined by the device IDs, provided by the app.
3.2. For instance, to achieve this, the customer backend application can query the Futurae user details GET /srv/auth/v1/users/{userID}
and check that the devices indeed belong to the mapped user.
3.3. This ensures that even if the access to the Apple or Google backup, where the recovery credential is stored, has been compromised, it cannot be used to recover access to an MFA device for the legitimate user without going through the extra user verification steps. For instance, the custom verification may involve username/password verification with the customer backend application after querying the migratable accounts.
4. [Auth API] Requesting a TSB token
4.1. Request a TSB token for the device IDs to be migrated. In a successful scenario, Futurae Auth API replies with 200 OK
and a response payload containing the TSB token. The device IDs need to be from a single physical device and app installation; if they are not, Futurae Auth API will reply with Error 400
.
4.2. Share the TSB token with your app frontend. The accounts can now be migrated.
5. [Futurae SDK] Using the TSB token: Account Recovery
5.1. Migrate the accounts including the TSB token in the migration request:
- On iOS, pass the binding token as the
MigrationParameters.bindingToken
parameter to themigrateAccounts
method. - On Android, pass the binding token as the
flowBindingToken
parameter to the FuturaemigrateAccounts
method.
5.2. Finally, handle the SDK account recovery response and display the result accordingly to the user.
Automatic Account Recovery flow with Trusted Session Binding
List of endpoints that support enabling Trusted Session Binding for account recovery
Enabling TSB for account recovery can be done either when creating a new enrollment or by modifying the properties of an already enrolled device.
-
Enable TSB at account recovery (as in diagram above)
Account Recovery with TSB can be enabled for mobile authenticators and FIDO device via the following endpoints during the enrollment request by Customer Backend by providing the body parameter"account_recovery_flow_binding_enabled": true
, in the following endpoints:
Auth API:
Enroll New User with Mobile Device
Enroll New Mobile Device for Existing User
Enroll New User with FIDO Device
Enroll New FIDO Device for Existing User
Admin API:
Enroll New User with Mobile App
Enroll New User with FIDO Device
Enroll New Device - Alternatively it is possible to modify an already existing enrolled device to enable TSB for account recovery:
Modify Device
For any technical support, do not hesitate to contact support@futurae.com.
Comments
0 comments
Article is closed for comments.