Lock Version 9

This document uses an outdated version of Lock (version 9). Learn how to migrate to version 10, or, if you're new to Lock, start out with the Lock 10 Documentation.

Lock: Migration Guide

This guide will walk you through the needed changes to migrate from Auth0Widget to Auth0Lock.

Initialization

While with the legacy Widget you had to:

var widget = new Auth0Widget({
  domain:         'your-domain.auth0.com',
  clientID:       'YOUR_CLIENT_ID',
  callbackURL:    'http:://your-domain.com/your_callback'
});

In the new Auth0Lock becomes:

var lock = new Auth0Lock('YOUR_CLIENT_ID', 'your-domain.auth0.com');

All other options that used to be passed along on the initialization process have been moved to the show API.

To learn how and when to set the callbackURL in Auth0Lock please read this guide.

For more information about Auth0Lock's initialization, check the [[Auth0Lock Initialization]] section.

API

The legacy .signin() method has been renamed to .showSignin(). Same applies to .signup() as .showSignup() and .reset() as .showReset(). There is also a .show() method which uses account's default settings to resolve what should be displayed.

The following example illustrates the main changes:

widget.signin({
  connections: [
    'facebook',
    'google-oauth2',
    'twitter',
    'Username-Password-Authentication'
  ]
});

In the new Auth0Lock becomes:

lock.showSignin({
  connections: [
    'facebook',
    'google-oauth2',
    'twitter',
    'Username-Password-Authentication'
  ]
});

Check the API documentation section in the README for a further walk through this methods.

Also, Auth0Widget callback order has changed: onload widget event has been removed as a callback and added as an event. The callback that was executed when the user has been signed in is now the second argument. For instance, this:

widget.signin({
  popup: true
}, null, function (err, profile) {

});

now is written as:

lock.showSignin({
  popup: true
}, function (err, profile) {

});

Customization

Some of the customization options have been renamed. You can check the [[Auth0Lock Customization]] section for a detailed specification on each allowed option.

You can also follow here the most important breaking changes on namings:

Widget Name Lock Name
callbackOnLocationHash responseType 1
showIcon Removed from API options 2
standalone closable
_avoidInitialFocus focusInput
showSignup disableSignupAction
showPassword disableResetAction
forgotLink resetLink
chrome Removed from API options 3
standalone closable
enableReturnUserExperience rememberLastLogin
enableADRealmDiscovery integratedWindowsLogin
username_style usernameStyle
userPwdConnectionName defaultUserPasswordConnection
extraParams authParams

1: responseType can be either token (callbackOnLocation: true) or code (callbackOnLocation: false).

2: The showIcon option has been removed. When icon property is provided it will be immediately displayed. In case you'd like to hide the default icon badge, the recommended way is by CSS customization. Check our [[UI customization]] page for that.

3: The chrome option has been removed. In case you'd like to hide the default icon badge, the recommended way is by CSS customization. Check our [[UI customization]] page for that.

The following options have been moved under authParams main property for a matter of semantics: access_token, scope, protocol, device, request_id, connection_scopes, nonce, offline_mode and state.

Events

Many of the event names changed. The general rule to apply for the proper handling is to replace the _ for (single space).

So, for example if you had signin_ready now it is signin ready.

Also, the one named transition_mode has been deprecated and removed from the list of Events.

For more information about events, check Auth0 Lock Events section.