Migrating from Lock v10 to v11

Versionv11

This guide includes all the information you need to update your Lock v10 application to Lock v11.

Migration demo

 

Migration steps

If you do not have the ability to use custom domains or prefer not to use them, and your application currently uses embedded login, the best migration path is to migrate to Universal Login.

Update Lock

Update the Lock library using npm or yarn.

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

# installation with yarn
yarn add auth0-lock

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-lock/build/lock.js"></script>

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

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

Configure your Auth0 application for embedded login

When implementing embedded login, Lock v11 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

Change calls to getProfile()

The deprecated getProfile() function was reimplemented in Lock 11. The previous implementation received an ID Token as a parameter and returned the user profile.

The new implementation requires an Access Token parameter instead.

Remove the oidcConformant parameter

When the oidcConformant flag was set to true, Lock 10 used Cross Origin Authentication, and did not use the '/usernamepassword/login' and '/ssodata' endpoints.

Given Lock 11 always always uses Cross Origin Authentication and does not use the '/ssodata' endpoint, this flag is not longer needed. If specified, it will be ignored.

Configure your custom domain

  1. Ensure that your application updates are made prior to setting up custom domains in your application, as the older versions of Lock v11 will not work when configured with a custom domain.

  2. Set up your custom domain in the Auth0 Dashboard.

  3. Use the custom domain when instantiating Lock.

var lock = new Auth0Lock('YOUR_CLIENT_ID', 'login.your-domain.com', options);
  1. Set the configurationBaseUrl option to https://cdn.auth0.com.
var options = {
  configurationBaseUrl: 'https://cdn.auth0.com'
};

The CDN URL varies by region. For regions outside of the US, use https://cdn.{region}.auth0.com (for example, use eu for Europe, au for Australia).

Management Application

If you intend to use the Auth0.js auth0.Management to get user information or perform account linking operations, you will need to instantiate a new Auth0 object with the Auth0 domain rather than your custom domain. The Management API only accepts Auth0 domains.

See the Auth0.js documentation on user management for more information on using the Management API in Auth0.js.

Verifying your migration

Once you have migrated your codebase, you should no longer see deprecation notes in your logs.

If you would like to be sure that your applications are no longer calling the legacy endpoints, you can go to the Dashboard under Tenant Settings > Advanced then scroll down to Migrations and toggle off the Legacy Lock API switch. Turning off this switch will disable the deprecated Lock / Auth0.js endpoints for your tenant, preventing them from being used at all.

Legacy Lock API

After disabling this switch, if the Legacy Lock API errors in your logs do not clear up or if turning it off results in failed logins, this is a sign that you have yet to completely remove all instances of legacy code from your applications.

Once migrations have been successfully performed in production environments, the switch can be toggled off and left off, to ensure that the deprecated features can no longer be used.

Behavioral changes in Lock v11

Usage in popup mode

When using popup mode in previous versions of Lock, a new browser window was opened and immediately closed in order to complete the authentication transaction. In Lock 11, that window is opened on a hidden iframe, providing a better user experience.

Last time you logged in with window with authorization code flow

Lock 11 will never show the Last time you logged in with window when using the Authorization Code Flow (that is, when specifying response_type='code'). It will always prompt for credentials.

Last time you logged in with window and redirects

The Last time you logged in with window will never do a redirect, even when the redirect option is set to true. Lock11 still emits the authenticated event and you should subscribe to that event to get the authentication result.

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

Single sign on using IP ranges

In earlier versions of Lock, you could configure an IP range in an Active Directory/LDAP connection. You could then use that range to allow integrated Windows Authentication if the user's IP was within the range. When this was true, Lock would display a button that users could click and get redirected to the integrated authentication dialog.

SSO With Lock 10 and Windows IP Ranges

This functionality has been removed from embedded login using Lock 11. There is no IP detection, and the user will need to type user and password in Lock. It is still available when using Universal Login.

Default values

Lock 11 will default the scope parameter to 'openid profile email'. This is to make the Last time you logged in with window work correctly.

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 Lock, you may get 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.

SSO with embedded authentication

Apps with embedded login must meet two criteria in order to have SSO.

  1. Both of the applications attempting SSO must be first-party applications. SSO with third party applications will not work.
  2. They need to make use of custom domains and have both the applications which intend to have SSO as well as the Auth0 tenant on the same domain. Traditionally, Auth0 domains are in the format foo.auth0.com, but custom domains allow you to use the same domain for each of the applications in question as well as your Auth0 tenant, preventing the risk of CSRF attacks.

Our recommendation is to use Universal Login instead of setting up SSO in embedded login scenarios. Universal Login is the most reliable and stable way to perform SSO, and is the only way to do so if you must use multiple domains for your applications, or use third-party applications.