Skip to main content

Adding authenticators

This guide will demonstrate how to use Authsignal to enroll users for MFA. There are two ways this can be done:

  1. Prompting users to select and enroll an authenticator themselves
  2. Enrolling users with a specific authenticator type automatically (if you already have their verified email or phone number)

Enabling authenticators

In the Authsignal Portal you can choose which authenticators should be enabled for your application in Settings -> Authenticators.

Enabling authenticators

For some authenticator types such as SMS you will need to configure the underling provider (e.g. Twilio or MessageBird).

Once an authenticator type is enabled, it will be available for users to select when they are enrolling via the Authsignal pre-built UI.

Self-service enrollment

One way users can enroll an authenticator themselves is by using the Authsignal pre-built UI.

Authsignal user enrollment screen which shows various authentication options

Retrieving a user's enrollment status

The getUser method lets you determine if a user of your app is currently enrolled (i.e. they have added at least one authenticator).

curl https://api.authsignal.com/v1/users/usr_123 \
-u YOUR_SECRET_KEY:

Displaying the self-service enrollment and management screens

If the user isn't enrolled for MFA yet, you might want to show a button which presents them with the option to enroll via the Authsignal pre-built UI. In this case, the onClick handler would make a call to your backend, which would then use the track method to initiate enrollment and return a URL to the app which can be used to enroll the user.

We also set the redirectToSettings param to true to let the user remain on the Authsignal pre-built UI when enrolling and add a second authenticator if they wish.

  curl https://api.authsignal.com/v1/users/usr_123/actions/enroll \
-u YOUR_SECRET_KEY: \
-H "Content-Type: application/json" \
-d '{"redirectUrl": "https://example.app", "redirectToSettings": true}'
note

You can pass "enroll" for the name of the action tracked here or a different value if you like. This value just determines what the action will be called when viewing it in the Authsignal Portal.

The redirectUrl you provide here is where users will be redirected back to in your application once they leave the Authsignal pre-built UI.

For security reasons, enrolled users will always be prompted to complete a challenge before they're able to manage existing MFA settings.

Authsignal presenting a challenge

If the redirectToSettings param here is true, the user will remain on the Authsignal pre-built UI after completing this challenge (where they can manage their MFA settings) instead of being redirected immediately back to your application.

Managing MFA settings

From here the user can enroll additional authenticator types and change their default authenticator.

Enrolling authenticators on the user's behalf

If you have already received and verified a user's email or phone number (for example during sign up) then you might wish to automatically enroll them for MFA, rather than prompting them to enroll themselves again.

You can do this by using the enrollVerifiedAuthenticator method:

curl https://api.authsignal.com/v1/users/usr_123/authenticators \
-u YOUR_SECRET_KEY: \
-H "Content-Type: application/json" \
-d '{"oobChannel": "SMS", "phoneNumber": "+64271234567"}'
caution

This option should only be used if you have already verified the user's email or phone number or (by sending them an email or SMS). Once this method is called, the user will be able to use this authenticator type for any future challenges.