Migrating from Auth0.js v7 to v9

Versionv9

This guide includes all the information you need to update Auth0.js from v7 to v9. Find out if you should upgrade or not by reading Migrating to Auth0.js v9.

The Auth0.js v7 to v8 Migration Guide has detailed information on how to migrate from v7 to v8, and that information is still valid, v7 is very similar to v9. This document will go over some common usage patterns, and focus on things that changed after that guide was created.

Migration Steps

Update auth0.js

Update the Auth0.js library using npm or yarn.

# installation with npm
npm install --save auth0-js

# installation with yarn
yarn add auth0-js

Once updated, you can add it to your build system or bring it in to your project with a script tag.

<script type="text/javascript" src="node_modules/auth0-js/build/auth0.js"></script>

If you do not want to use a package manager, you can retrieve Auth0.js from Auth0's CDN.

<script src="https://cdn.auth0.com/js/auth0/9.5.1/auth0.min.js"></script>

Using Auth0.js to Log In Users

Using Auth0.js v7

var auth0 = new Auth0({
  domain:'YOUR_AUTH0_DOMAIN',
  clientID: 'YOUR_CLIENT_ID',
  responseType: 'token'
});

// With Universal Login
auth0.login({});

// With a social or enterprise connection
auth0.login({
  connection: 'twitter'
});

// With username and password
auth0.login({
  connection: 'my-db-connection',
  username: 'the-username',
  password: 'the-password'
});

Using Auth0.js v9

var webAuth = new auth0.WebAuth({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientID: 'YOUR_CLIENT_ID',
  responseType: 'token id_token'
});

// with Universal Login
webAuth.authorize({});

// with a social or enterprise connection
webAuth.authorize({
  connection: 'twitter'
});

// with username and password
webAuth.login({
  realm: 'my-db-connection',
  username: 'the-username',
  //email: 'the@email.com',
  password: 'the-password'
});

Using Auth0.js to log in users in 'popup mode'

Using Auth0.js v7

var auth0 = new Auth0({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientID: 'YOUR_CLIENT_ID',
  responseType: 'token'
});

// With Universal Login
auth0.login({
  popup: true
});

//with a social or enterprise connection
auth0.login({
  popup: true,
  connection: 'twitter'
});

//with username and password
auth0.login({
  popup: true,
  connection: 'my-db-connection',
  username: 'the-username',
  password: 'the-password'
});

Using Auth0.js v9

var webAuth = new auth0.WebAuth({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientID: 'YOUR_CLIENT_ID',
  responseType: 'token'
});

// with Universal Login
webAuth.popup.authorize({});

// with a social or enterprise connection
webAuth.popup.authorize({
  connection: 'twitter'
});

// with username and password
webAuth.popup.loginWithCredentials({
  connection: 'my-db-connection',
  username: 'the-username',
  //email: 'the@email.com',
  password: 'the-password'
});

Using Auth0.js to sign up users

Using Auth0.js v7

var auth0 = new Auth0({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientID: 'YOUR_CLIENT_ID',
  responseType: 'token'
});

// signup only
auth0.signup({
  connection: 'my-db-connection',
  username: 'the-username',
  password: 'the-password',
  auto_login: false
}, function (err) {
  if (err) return alert('Something went wrong: ' + err.message);
  alert('success signup without login!')
});

// signup and login
auth0.signup({
  connection: 'my-db-connection',
  username: 'the-username',
  password: 'the-password',
  auto_login: true
}, function (err) {
  if (err) alert('Something went wrong: ' + err.message);
});

Using Auth0.js v9

var webAuth = new auth0.WebAuth({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientID: 'YOUR_CLIENT_ID',
  responseType: 'token'
});

// signup only

webAuth.signup({
  connection: 'my-db-connection',
  email: 'the-email',
  password: 'the-password',
  user_metadata: { plan: 'silver', team_id: 'a111' }
}, function (err) {
  if (err) return alert('Something went wrong: ' + err.message);
  alert('success signup without login!')
});

// signup and login
webAuth.redirect.signupAndLogin({
  connection: 'my-db-connection',
  email: 'the-email',
  password: 'the-password',
  user_metadata: { plan: 'silver', team_id: 'a111' }
}, function(err) {
  if (err) alert('Something went wrong: ' + err.message);
});

Using Auth0.js to log in users using passwordless

Using Auth0.js v7

var auth0 = new Auth0({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientID: 'YOUR_CLIENT_ID',
  responseType: 'token'
});

// with a magic link sent via email
auth0.requestMagicLink(
  {
    email: 'the@email.com'
  },
  function(err) {}
);

// with a code sent via email
auth0.requestEmailCode(
  {
    email: 'the@email.com'
  },
  function(err) {}
);

// verifying the email code
auth0.verifyEmailCode(
  {
    email: 'the@email.com',
    code: 'the-code'
  },
  function(err, result) {}
);

// with a code sent via sms
auth0.requestSMSCode(
  {
    phoneNumber: '+the_phone_number'
  },
  function(err) {}
);

// verifying the sms code
auth0.verifySMSCode(
  {
    phoneNumber: '+the_phone_number',
    code: 'the-code'
  },
  function(err, result) {}
);

Using Auth0.js v9

var webAuth = new auth0.WebAuth({
  domain: ''YOUR_AUTH0_DOMAIN'',
  clientID: ''YOUR_CLIENT_ID'',
  responseType: 'token'
});

// with a magic link sent via email
webAuth.passwordlessStart({
  send: 'link',
  email: 'the@email.com',
  connection: 'email'
});

// with a code sent via email
webAuth.passwordlessStart({
  send: 'code',
  email: 'the@email.com',
  connection: 'email'
});

// verifying the email code
webAuth.passwordlessLogin({
  email: 'the@email.com',
  verificationCode: 'the-code',
  connection: 'email'
});

// with a code sent via sms
webAuth.passwordlessStart({
  phoneNumber: '+the_phone_number',
  connection: 'sms'
});

// verifying the sms code
webAuth.passwordlessLogin({
  phoneNumber: '+the_phone_number',
  verificationCode: 'the-code',
  connection: 'sms'
});

Configure your Auth0 application for embedded login

When implementing embedded login, Auth0.js v9 will use cross-origin calls inside hidden iframes to perform authentication. To make sure this can be done securely, Auth0 needs to know the domains where you will be hosting your applications.

Add the domain to the Allowed Web Origins field. You can find this field in the Application Settings area of your Dashboard.

Allowed Web Origins

Review calls to getSSOData()

The deprecated getSSOData() function was reimplemented in Auth0.js v9 to simplify migration from older versions, but the behavior is not exactly the same.

The function will not work as expected when you use it in Web Applications that use the Authorization Code Flow (such as when you specify response_type='code'). It will always return that there is not a current session.

If you want to avoid showing the Lock dialog when there is an existing session in the server, you can use the checkSession() function in Auth0.js.

We recommend that you do not use getSSOData() and use checkSession() instead. Note that in order for checkSession() to work properly, it requires that you set the Allowed Web Origins field in the dashboard.

Note that checkSession() triggers any rules you may have set up, whereas getSSOData() does not. It is possible that this could cause unintended behavior depending on what rules you have set up (if any) so you should check on your rules in the Dashboard prior to switching methods.

If you are going to keep using getSSOData(), take into account the changes in the return values described in the table below. In most applications, the only value that was actually used was the sso property, which still has the same semantics.

Property Old Value New Value
sso true if user has an existing session, false if not The same
sessionClients List of applications ids the user has active sessions with List with a single element with the client id configured in auth0.js
lastUsedClientId The client id for the last active connection The last application used when authenticating from the current browsers
lastUsedUserId The user id for the current session The same
lastUsedUsername User's email or name The same (requires scope=’openid profile email’)
lastUsedConnection Last used connection and strategy. Last connection used when authenticated from the current browser. It will be null if the user authenticated via Universal Login. It will not return strategy, only name

In order for the function to work properly, you need to ask for scope='openid profile email' when you initialize Auth0.js.

Migrating from legacy authentication flows

The OIDC conformant flows disallow certain practices that were common when developing applications with older versions of the library, like using Refresh Tokens, using ID Tokens to call APIs, and accessing non-standard claims in the user profile.

Follow the steps in the Migration from Legacy Authentication Flows to learn what changes you need to make in your application.

Behavioral Changes

Default values

Auth0.js v9 will default the value of the scope parameter to openid profile email.

If you are running your website from http://localhost or http://127.0.0.1 and you do not specify the openid profile email scope when initializing auth0.js, calling the getSSOData() method will result in the following error in the browser console:

Consent required. When using `getSSOData`, the user has to be authenticated with the following scope: `openid profile email`

This will not happen when you run your application in production, or if you specify the required scope. You can read more about this scenario in the documentation on skipping consent for first-party applications.