Skip to main content

Enrolling 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 Prebuilt MFA page.

Self-service enrollment

One way users can enroll an authenticator themselves is by using the Authsignal Prebuilt MFA page.

Authsignal user enrollment screen which shows various authentication options

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://signal.authsignal.com/v1/users/usr_123 \
-u YOUR_SECRET_KEY:

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 Prebuilt MFA page. 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.

  curl https://signal.authsignal.com/v1/users/usr_123/actions/enroll \
-u YOUR_SECRET_KEY: \
-H "Content-Type: application/json" \
-d '{"redirectUrl": "https://example.app"}'
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 Prebuilt MFA page.

If the user is already enrolled for MFA, on the other hand, the url will load a page which lets them manage their existing MFA settings. If you wanted to differentiate this action from your enrollment action in the Authsignal Portal, for example, you could track an action called manageSettings:

  curl https://signal.authsignal.com/v1/users/usr_123/actions/manageSettings \
-u YOUR_SECRET_KEY: \
-H "Content-Type: application/json" \
-d '{"redirectUrl": "https://example.app/settings/mfa"}'

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

Authsignal presenting a MFA challenge

If the redirectToSettings param here is true, the user will remain on the Authsignal Prebuilt MFA page 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://signal.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 MFA challenges.