Migration Guide for lock-passwordless to Lock v11 with Passwordless Mode

Versionv11

The following instructions assume you are migrating from the lock-passwordless widget to Lock v11.2+ using Passwordless Mode.

The lock-passwordless widget was previously a standalone library, separate from Lock. Now, you can migrate your apps to use the Passwordless Mode which is integrated directly into Lock v11. Lock v11 with Passwordless Mode is the latest method by which to deploy a login widget for passwordless authentication in your apps.

To get started, you will need to remove lock-passwordless from your project, and instead include the latest release version of Lock v11.

To use Passwordless Mode, you must use Lock v11.2 or above.

Beyond that, you will then need to take a careful look at each of the sections in this migration guide in order to find out which changes you will need to make to your implementation. Of particular importance will be the following:

  • The initialization of Auth0LockPasswordless
  • Your calls to Lock methods (now the same methods as used in Lock v11)
  • Your previously implemented customization options, which will need inspected and changed to use the corresponding options for Lock v11.

General changes and additions

Importing Auth0LockPasswordless

You can import Auth0LockPasswordless in the same ways as you would normally import Lock; using the CDN or via NPM.

Using the CDN

If you're loading from the CDN, you can still use Auth0LockPasswordless. The difference is that you'll provide your options in the constructor, like we do with Auth0Lock:


    <script src="http://cdn.auth0.com/js/lock-passwordless-2.2.3.min.js"></script>
    <script>
      var lock = new Auth0LockPasswordless(clientID, domain);
    </script>
    

    <script src="https://cdn.auth0.com/js/lock/11.6.1/lock.min.js"></script>
    <script>
      // example use of options
      var options = {
        closable: false
      }
      var lock = new Auth0LockPasswordless(clientID, domain, options);
    </script>
    

Using npm + module bundler


    import Auth0LockPasswordless from 'auth0-lock-passwordless';
    var lock = new Auth0LockPasswordless(clientID, domain);
    

    import {Auth0LockPasswordless} from 'auth0-lock';
    var options = {
      closable: false
    };
    var lock = new Auth0LockPasswordless(clientID, domain, options);
    

Initialization options

Auth0LockPasswordless has the same options available as Auth0Lock in addition to a single new option that determines if you want to use a Magic Link or a Email Code when using an email passwordless connection. For this property, passwordlessMethod, only two values are accepted:

  • code if you want to use an Email Code
  • link if you want to use a Magic Link

    var options = {
      passwordlessMethod: 'code'
    };
    var lock = new Auth0LockPasswordless(clientID, domain, options);
    

Choose between SMS or email

We recommend that you setup which passwordless connections you want enabled in the dashboard, but if you want to have more than one passwordless connection enabled in the dashboard, you can restrict Auth0LockPasswordless to use only one of them using the allowedConnections option. If you have both sms and email passwordless connections enabled in the dashboard, Auth0LockPasswordless will use email by default.


    var options = {
      allowedConnections: ['sms']
    };
    var lock = new Auth0LockPasswordless(clientID, domain, options);
    

    var options = {
      allowedConnections: ['email'],
      passwordlessMethod: 'code'
    };
    var lock = new Auth0LockPasswordless(clientID, domain, options);
    

Show the widget

In the old lock-passwordless, you could call the passwordless method directly (sms, socialOrMagiclink, socialOrSms etc). In Lock v11, you'll have to use the show method in order to display the widget.

var lock = new Auth0LockPasswordless(clientID, domain);
lock.show();

Subscribe to events

Lock exposes a few events that you can subscribe to in order to be notified when the user is authenticated or an error occurs. So, instead of callbacks from lock-passwordless, you have to subscribe to events that you want to know about. To read more about Lock events, see here.

var lock = new Auth0LockPasswordless(clientID, domain);
lock.on("authenticated", function(authResult) {
  alert(authResult.accessToken);
});

Customization options

Some options have to be renamed.

Further Reading