Migrating from Lock v9 to v11

Versionv11

This guide includes all the information you need to update your Lock v9 applications to Lock v11.

Migration Steps

Given that Lock v10 is very similar to Lock v11 you can read the Lock v9 to Lock v10 migration guide.

Building Single Page Applications with Lock v9 has some key differences with the way they should be built in Lock v11. Lock v11 uses OIDC conformant APIs that are more secure, and some of the coding patterns with Lock v9 need to be changed.

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>

Using Lock in SPAs with Popup Mode

In Lock v9 the code to use popup mode looked similar to the below example.

var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_AUTH0_DOMAIN');
function login()
{
    lock.show({
            responseType : "token",
            authParams: {
                scope: 'openid email offline_access'
            }
        },
        function (err, profile, id_token, access_token, state, refresh_token) {
            if (!err) {
                setSession(profile, id_token, access_token, refresh_token);
                lock.getProfile(hash.id_token, function(err, userInfo) {
                    if (!err) {
                        /// use the userInfo
                    }
                });
            }
        }
    })
}

In Lock v11, the code would instead use the following format.

var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_AUTH0_DOMAIN', {
        {
            popup: true,
            auth: {
                responseType: 'token id_token',
                audience: 'https://' + 'YOUR_AUTH0_DOMAIN' + '/userinfo',
                params: {
                    scope: 'openid email profile'
                }
            }
        }
    );

lock.on('authenticated', function(authResult) {
    if (authResult && authResult.accessToken && authResult.idToken) {
        setSession(authResult);

        lock.getUserInfo(authResult.accessToken, function(err, userInfo) {
             if (!err) {
                // use the userInfo
            }
        });
    }
});
function login()
{
    lock.show()
}

Note that the parameters that were passed to show() in Lock v9 are used to initialize Lock in Lock v11, and that the callback specified in show() is replaced by an authenticated event handler.

Using Lock in SPAs with Redirect Mode

In Lock v9 the code to use redirect mode looked similar to the below example.

var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_AUTH0_DOMAIN');
var hash = lock.parseHash();

if (hash) {
    if (!hash.error) {
        setSession(hash.profile, hash.id_token, hash.access_token, hash.refresh_token);

        lock.getProfile(hash.id_token, function(err, userInfo) {
            if (!err) {
                // use the userInfo
            }
        });
    } 
}

function login() {
    lock.show({
        callbackURL: 'https://YOUR_APP/callback',
        responseType : "token",
        authParams: {
            scope: 'openid email offline_access'
        }
    });
}

In Lock v11, the code should instead use the following format.

var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_AUTH0_DOMAIN', {
        {
            auth: {
                redirectUrl: 'https://YOUR_APP/callback',
                responseType: 'token id_token',
                params: {
                    scope: 'openid email profile'
                }
            }
        }
    );

lock.on('authenticated', function(authResult) {
    if (authResult && authResult.accessToken && authResult.idToken) {
        setSession(authResult);
        // use authResult.idTokenPayload for profile information
    }
});

function login() {
    lock.show()
}

Note that the parameters that were passed to show() in Lock v9 are used to initialize Lock in Lock v11, and that instead of calling parseHash(), you need to write an authenticated event handler.

Using Lock in Web Applications

When using Lock v9 for Web Applications, the code would be similar to the below example.

var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_AUTH0_DOMAIN');

function login() {
    lock.show({
     auth: {
      redirectUrl: 'https://YOUR_APP/callback',
      responseType: 'code',
      params: {
        scope: 'openid profile email' 
      }
    }
  }

In Lock v11, the code should instead use the following format.

var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_AUTH0_DOMAIN', {
    {
        auth: {
            redirectUrl: 'https://YOUR_APP/callback',
            responseType: 'code',
            params: {
                scope: 'openid email profile'
            }
        }
    }
);

function login() {
    lock.show()
}

Note that, once more, the parameters that were passed to show() in Lock v9 are used to initialize Lock in Lock v11.

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

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.

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.

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.

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.

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.