Auth0

This guide will demonstrate how to integrate Authsignal with Auth0 by creating a Custom Action for the Login / Post-Login trigger.

The end result will be to allow users to complete an MFA challenge after they login with their username and password, redirecting them from the Auth0 Universal Login Page to Authsignal's pre-built UI.

The integration follows Auth0’s official guidelines for redirecting users after login to do custom MFA. You can learn more here about how to Redirect with Actions in Auth0.

User flow

1. The user enters their username and password in the Auth0 Universal Login page.

2. The user is redirected to Authsignal's pre-built UI to complete an MFA challenge.

3. The user is logged in if the challenge is completed successfully.

Integration steps

1. Create an action

In the Auth0 Dashboard, go to Actions → Library and select “Build Custom”. Then select the “Login / Post Login” trigger and give the action an appropriate name (for example “post-login-mfa”).

2. Add your secret

Now your action has been created, create a new secret called AUTHSIGNAL_SECRET and provide the value of your secret from the Api Keys section in the Authsignal Portal.

3. Add dependencies

Add the @authsignal/node dependency.

4. Add the action code

Add the following code snippet to the action.

const { handleAuth0ExecutePostLogin, handleAuth0ContinuePostLogin } = require("@authsignal/node");

exports.onExecutePostLogin = handleAuth0ExecutePostLogin;

exports.onContinuePostLogin = handleAuth0ContinuePostLogin;

If using a non-US region (e.g. AU or EU) you will need to override the base URL as follows:

const { handleAuth0ExecutePostLogin, handleAuth0ContinuePostLogin } = require("@authsignal/node");

const apiBaseUrl = "https://eu.api.authsignal.com/v1";

exports.onExecutePostLogin = async (event, api) => {
  await handleAuth0ExecutePostLogin(event, api, { apiBaseUrl });
};

exports.onContinuePostLogin = async (event, api) => {
  await handleAuth0ContinuePostLogin(event, api, { apiBaseUrl });
};

5. Connect your action to the Login flow

Now connect your action in the Flows section of the Auth0 Dashboard by dragging it into the Login flow.

6. Configure the action in Authsignal

Once the previous steps have been completed, the next time the Auth0 action is run you will see an action appear in the Authsignal Portal called “Auth0 Login”. You will need to set the default outcome for this action to CHALLENGE and save it.

That’s it! You’ve done everything required to add MFA to your Auth0 login flow using Authsignal.

Advanced options

Opting out for social or federated logins

You may want to avoid redirecting users to the Challenge UI if they are using an external social login provider, for example Google or Facebook. You can easily do this by checking the connection on the event object.

const { handleAuth0ExecutePostLogin, handleAuth0ContinuePostLogin } = require("@authsignal/node");

/**
 * @param {Event} event
 * @param {PostLoginAPI} api
 */
exports.onExecutePostLogin = async (event, api) => {
  // Only redirect for auth0 database connections, not social or federated
  if (event.connection.strategy === "auth0") {
    await handleAuth0ExecutePostLogin(event, api);
  }
};

exports.onContinuePostLogin = handleAuth0ContinuePostLogin;

Using the server client directly

To allow for more customization and control (for example, requiring MFA only for some users based on rules and conditions) you can also use the Authsignal Node SDK directly from within your Auth0 Custom Action.

const { Authsignal, UserActionState } = require("@authsignal/node");

/**
 * @param {Event} event
 * @param {PostLoginAPI} api
 */
exports.onExecutePostLogin = async (event, api) => {
  // Redirects are not possible for refresh token exchange
  // https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/redirect-with-actions#refresh-tokens
  if (event.transaction?.protocol === "oauth2-refresh-token") {
    return;
  }

  const secret = event.secrets.AUTHSIGNAL_SECRET;
  const userId = event.user.user_id;
  const redirectUrl = `https://${event.request.hostname}/continue`;

  const authsignal = new Authsignal({ secret });

  const { state, url, isEnrolled } = await authsignal.track({
    action: "auth0-login",
    userId,
    redirectUrl,
    // optional
    email: event.user.email,
    ipAddress: event.request.ip,
    userAgent: event.request.user_agent,
    deviceId: event.request.query?.["device_id"],
  });

  // Redirect to the Challenge UI if a challenge is required
  // Also redirect users not yet enrolled so they can enroll
  if (state === "CHALLENGE_REQUIRED" || !isEnrolled) {
    api.redirect.sendUserTo(url);
  }
};

/**
 * @param {Event} event
 * @param {PostLoginAPI} api
 */
exports.onContinuePostLogin = async (event, api) => {
  const secret = event.secrets.AUTHSIGNAL_SECRET;
  const userId = event.user.user_id;

  const authsignal = new Authsignal({ secret });

  const payload = api.redirect.validateToken({
    secret,
    tokenParameterName: "token",
  });

  const result = await authsignal.getAction({
    action: "auth0-login",
    userId,
    idempotencyKey: payload.other.idempotencyKey,
  });

  if (result && result.state !== "CHALLENGE_SUCCEEDED") {
    api.access.deny("Access denied");
  }
};

Passing a device ID

It is often useful to know the user's device when configuring more fine-grained rules - for example, to trigger challenges when a new device is detected.

Our Auth0 integration allows passing a device ID via authorization parameters. For example, if using the Authsignal Web SDK you can pass the anonymousId value (which is persisted automatically via cookies):

const authsignal = new Authsignal({
  baseUrl: "https://api.authsignal.com/v1",
  tenantId: "YOUR_TENANT_ID",
});

...

await loginWithRedirect({
  authorizationParams: { device_id: authsignal.anonymousId },
});