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 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
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"];

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
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"}'

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

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

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

$payload = array("redirectUrl" => $redirectUrl));

$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 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
Node.js
Ruby
Python
PHP

  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"}'

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

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

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

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

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

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.