UNLOQ as the second factor

UNLOQ can also be implemented as the second-factor in your application, which enabling you to preserve your current login mechanism and add an additional layer of protection. A typical application that would like to add this layer can choose between two types of implementation: using the JavaScript widget or performing server-to-server API calls

The first thing to do is to modify your account store table, by adding a field string second_factor (or equivalent) that can have the value UNLOQ with the default value of null (or equivalent). This field will tell us which users opted-in to use UNLOQ as their second factor. In this scenario, you can provide multiple types of second-factor solutions, but we'll focus on handling UNLOQ.

Next, under your account settings page (or equivalent), display an Enable UNLOQ as second-factor button for accounts that have second_factor set to null. In order to enable second factor, a user must have the UNLOQ app (or your custom mobile app) installed and an account created. In this scenario, we assume the e-mail address the user used to setup his UNLOQ app is the same he used to login to your application.

When a user clicks the button, have the browser do a POST request to your server's /enroll (or equivalent) endpoint. Then, have your server perform a POST request to the UNLOQ API's /v1/enroll endpoint. If the user was previously enrolled or has used UNLOQ to login to your application, a push notification will be sent to the user's device, asking him to approve this action. Once the user agrees, the response will end with a success, and you can set second_factor to UNLOQ for your user's database entry, thus finalizing the enroll process.

After enabling 2FA for your user, it's time to use it at login. In your application's login functionality, right before creating the user's session (token, credentials, etc), check the requesting account's second_factor field. If this is set to UNLOQ, you can do one of the following implementations:

• Widget implementation - On the user's session, set a was_2fa variable, set to false (this will tell us that the user did not finalize the 2FA) and redirect him to /login/two-step (or equivalent). At this point, you can render the two-step page, including the UNLOQ Widget script.
  The user will then go through the UNLOQ authentication process and will be finally redirected to your application's login widget's URL, together with an access token, located in the query string's token key. (?token=)
  In your login route (controller, etc), call the UNLOQ API's /v1/token endpoint, sending the token from the query string as payload. Once the call successfully ends, you can then set the user's session was_2fa to true, indicating that the user has completed the challenge and proceed normally to redirect him to the dashboard (or equivalent).
• Server-to-server implementation - Once you've found the user and matched their password, call the UNLOQ API's /v1/authenticate endpoint, sending the user's email as payload. The user will then be asked to approve the authentication request, and the API call will return an access token.
  Next, use the generated access token to call the /v1/token endpoint, in order to retrieve the user's information and validate the token. If the result is successful, set the user's session was_2fa to true, indicating that the user has completed the challenge, and proceed normally to redirect him to the dashboard (or equivalent).

Additionally, under the account settings page (or equivalent), if the current user has second_factor set to UNLOQ, you can present a "Disable two-step verification" button. Once clicked, it will perform a request to your server, which in terms will update the user's second_factor field to null, thus disabling the two-step verification.

In both cases, the session check middleware (the piece of functionality that checks that a session exists and the user is logged in) should check for the was_2fa variable from the user's session, except for your application's login widget's URL (by default, /uauth/login) or the /login/two-step (or equivalent) route. If was_2fa is set to false, have the user redirected back to /login or /login/two-step.
Note: if the user does not have two-step verification enabled, during the login process, set the was_2fa< session key to true, so that the user is not redirected by the session check middleware.

Both cases will offer two-step verification using out-of-band communication.

Have a question? You can always send us an email at support@unloq.io, or contact us on chat.

For security related concerns, please visit our Security page.