Lock 9 to Lock 10 Migration Guide

The following instructions assume you are migrating from Lock 9 to the latest Lock 10. If you are upgrading from a preview release of Lock 10, please refer to the preview changes. Otherwise, read on!

If you just want a quick list of new features to see what changes Lock 10 has introduced, take a look at the new features page.

The goal of this migration guide is to provide you with all of the information you would need to update your Lock 9 installation to Lock 10. Of course, your first step is to install or include the latest version of Lock 10 rather than Lock 9. Beyond that, take a careful look at each of the areas on this page. You will need to change your implementation to reflect the new changes, not only the initialization of Lock and your calls to Lock methods, but especially any configuration options you were implementing may need inspected and changed. Take a look below for more information!

General Changes and Additions

User Profiles

  • The profile is no longer fetched automatically after a successful login, you need to call lock.getUserInfo.

Redirect Mode vs Popup Mode

  • Lock now uses Redirect Mode by default. To use Popup Mode, you must enable this explicitly with the redirect option auth: { redirect: false }.
  • You no longer need to call parseHash when implementing Redirect Mode. The data returned by that method is provided to the authenticated event listener.

Configuration and Customization Options

  • The show method is no longer the place to include options to configure Lock's appearance or behavior. You instead pass the options to the constructor and then you listen for an authenticated event instead of providing a callback.
var options = {
  theme: {
    logo: 'https://example.com/logo.png',
    primaryColor: '#31324F'
  }
};
var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_AUTH0_DOMAIN', options);

Lock 10 does allow some configuration methods to be added to the show() method in order to override the defaults for special use cases. See more in the Lock api doc.

Events Changed

  • Events have significantly changed between Lock 9 and Lock 10. The events that were emitted in Lock 9 are no longer used in Lock 10. The new events list for Lock 10 can be found on the Lock 10 API page.
  • Important notes about the new authenticated event: The authenticated event listener has a single argument, an authResult object. This object contains the following properties: idToken, accessToken, state, refreshToken and idTokenPayload. Most of them correspond to the arguments which were previously passed to the show method's callback.

Internationalization

  • Not all languages supported by Lock v9 are supported by Lock v10. Please see the i18n directory in the GitHub repository for a current list of supported languages in Lock.

Removed Methods

  • The showSignin, showSignup and showReset methods are no longer available. You can emulate the behavior of this options with the initialScreen, allowLogin, allowSignUp and allowForgotPassword options.
  • The getClient method and the $auth0 property are no longer available. You can, instead, simply instantiate Auth0 when using functionality from auth0.js. If you need help with how to do this, see the Using Lock with auth0js page.

Changes to configuration Options

Some existing options suffered changes, in addition to the beforementioned removals and additions. Please see below for brief descriptions, or consult the configuration reference for more information.

Display Options

  • The connections option was renamed to allowedConnections.
  • The focusInput option was renamed to autofocus.
  • The gravatar option was renamed to avatar and instead of taking true and false it now takes null or an object.
  • The dict option was split into language and languageDictionary. The language option allows you to set the base dictionary for a given language and the languageDictionary option allows you to overwrite any translation. Also, the structure of the dictionary has been changed.

Theming Options

  • The icon option was renamed to logo and namespaced under theme. Now you use it like this theme: {logo: "https://example.com/icon.png"}.
  • The primaryColor option was namespaced under theme. Now you use it like this theme: {primaryColor: "#ec4889"}.

Social Options

  • The socialBigButtons option was renamed to socialButtonStyle and its possible values are "small" or "big" instead of true or false.

Authentication Options

  • The authParams option was renamed to params and namespaced under auth. Now you use it like this auth: {params: {myparam: "myvalue"}}.
  • The connection_scopes parameter under authParams is now connectionScopes (under the auth option) auth: {connectionScopes: {'facebook': ['scope1', 'scope2']}}.
  • The popup option was replaced by redirect which is namespaced under auth. If you previously used popup: true now you need to provide auth: {redirect: false}.
  • The callbackURL option was renamed to redirectUrl and namespaced under auth. Now you use it like this auth: {redirectUrl: "https://example.com/callback"}.
  • The responseType option was namespaced under auth. Now you use it like this auth: {responseType: "code"}.
  • The sso option was namespaced under auth. Now you use it like this auth: {sso: false}.

Database Options

Other Options

  • The forceJSONP option was removed.

Further Reading

  • Some other options were added, see New Features page for details.
  • Check out the configuration page for more details on all of the configuration options that are available.
  • Take a look at the api page for more details on Lock 10's API.