Lock: Authentication Modes

This document covers an outdated version of Lock. We recommend you to upgrade to v10.

After Auth0 Lock is opened, you can choose any of the Identity Providers (IdP) that Auth0 has, to Login. Depending on how the IdP Web/App is opened, a different authentication mode is used.

Redirect Mode

If after you click on the IdP button (Facebook for example), the Webapp you built gets redirected to Facebook, it means you're using Redirect Mode. Once you successfully login to Facebook, Facebook will redirect you back to your app (through Auth0). This means that if you had any state in memory in your WebApp, it will be lost. This is why a successful login with Redirect mode cannot be handled with a callback and must be handled with the parseHash method.

Example: Redirect Mode in SPA

In this first example you'll see that a callbackURL isn't set. That's because by default the callbackURL is set to location.href which means the current URL.

Optionally, you can set the callbackURL to whatever you need. Please bear in mind that if you do, you'll also need to specify responseType: token as part of the options.

var lock = new Auth0Lock(YOUR_CLIENT_ID, YOUR_AUTH0_DOMAIN);

var hash = lock.parseHash();

if (hash) {
  if (hash.error) {
    console.log("There was an error logging in", hash.error);
  } else {
    lock.getProfile(hash.id_token, function(err, profile) {
      if (err) {
        console.log('Cannot get user :(', err);
        return;
      }

      console.log("Hey dude", profile);
    });
  }
}

lock.show();

Example: Redirect Mode in Regular Web Apps

When you're doing a Regular web app, you need that after a successful login through Auth0, your app is redirected to a callback endpoint that you've created in your server. That callback endpoint will receive the code from Auth0 which must then be exchanged for an access_token to get the user information.

This means that in this case, only redirect mode makes sense.

var lock = new Auth0Lock(YOUR_CLIENT_ID, YOUR_AUTH0_DOMAIN);

lock.show({
  callbackURL: 'http://myUrl.com/auth/callback'
});

If after you click on the IdP button (Facebook for example), a popup (new tab or window) is opened, it means you're using Popup Mode. In that popup, you'll see that Facebook page is displayed. Once you successfully login to Facebook, the popup will be closed and your WebApp will recognize that the user has been authenticated. The WebApp has never been redirected to any other page. This means that you won't lose any state in memory that your application had. This is why we can handle successful login with a callback in this case.

There is a known bug that prevents popup mode from functioning properly in Android or Firefox on iOS, and in Internet Explorer under certain circumstances. As such we recommend only using redirect mode (or if popup mode is absolutely required, detecting these special cases in which popup mode will fail and selectively enabling redirect mode).

Database connections and popup mode

Some Auth0 features such as MFA and SSO between multiple applications depend on users being redirected to Auth0 to set a cookie on 'YOUR_AUTH0_DOMAIN'.

When using popup mode, a popup window will be displayed in order to set this cookie and display MFA prompts if necessary; this popup window will be blank if users are not prompted for MFA, which might not be a desirable UX. The reason for this is that cross-origin requests sent from your application to Auth0 are not be able to set cookies.

If you do not want to display a popup window and do not need MFA or SSO between multiple applications, you can set sso: false when using Lock or auth0.js.

For example:

auth.signin({
  sso: false,
  ...
}, function (err, profile, token) { ... });

Example: Popup Mode in SPA

Below is an example of an implementation of popup mode in a Single Page Application:

var lock = new Auth0Lock(YOUR_CLIENT_ID, YOUR_AUTH0_DOMAIN);

lock.show(function(err, profile, id_token) {
  if (err) {
    console.log("There was an error :/", err);
    return;
  }

  console.log("Hey dude", profile);
})