Enrolling authenticators

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

Prompting users to select and enroll an authenticator themselves
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 Challenge UI.

Self-service enrollment

One way users can enroll an authenticator themselves is by using the Challenge 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
Node.js
Ruby
Python
PHP

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

const result = await authsignal.getUser({ userId: "usr_123" });

const isEnrolled = result.isEnrolled;

result = Authsignal.get_user(user_id: "usr_123")

is_enrolled = result[:is_enrolled]

result = authsignal_client.get_user(user_id="usr_123")

is_enrolled = result["isEnrolled"]

$result = Authsignal::getUser(userId: "usr_123");

$isEnrolled = $result["isEnrolled"];

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 Challenge 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 Challenge UI when enrolling and add a second authenticator if they wish.

cURL
Node.js
Ruby
Python
PHP

  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", "redirectToSettings": true}'

const { url } = await authsignal.track({
  action: "enroll",
  userId: "usr_123",
  redirectUrl: "https://example.app",
  redirectToSettings: true
});

result = Authsignal.track_action({
        action_code: "enroll",
        user_id: "usr_123",
        redirect_url: "https://example.app",
        redirect_to_settings: true
    }
)

result = authsignal_client.track_action(
    action_code="enroll",
    user_id="usr_123",
    payload={
        "redirectUrl": "https://www.example.app",
        "redirectToSettings": true
    }
)

$payload = array("redirectUrl" => $redirectUrl, "redirectToSettings" => true));

$result = Authsignal::trackAction(actionCode: "enroll",
                                  userId: "usr_123",
                                  payload: $payload);

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 Challenge UI.

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 Challenge 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.