Lock v11 for Web
Lock is an embeddable login form, configurable to your needs, and recommended for use in single-page apps. It enables you to easily add social identity providers, so that your users can login seamlessly using any provider they want.
You can install Lock v11 via several methods. Select any of the following installation sources that best suit your environment and application.
Install via npm:
Install via bower:
Include via our CDN (Replace
.y with the latest minor and patch release numbers from the Lock Github repository:
Updating patch versions
It is recommended that production applications use a specific patch version, or at the very least a specific minor version. Regardless of the method by which Lock is included, the recommendation is that the version should be locked down and only manually updated, to ensure that those updates do not adversely affect your implementation. Check the GitHub repository for a current list of releases.
If you are targeting mobile audiences, Auth0 recommends that you add the following meta tag to your application's
If you are using browserify or webpack to build your project and bundle its dependencies, after installing the
auth0-lock module, you will need to bundle it with all its dependencies. Examples are available for Browserify and webpack.
Embedding Lock within your application requires cross-origin authentication to be properly configured. Specifically, you need to set the Allowed Web Origins property to the domain making the request. You can find this field in the Application Settings.
Make sure you read about the limitations of cross-origin authentication before implementing Lock.
1. Initializing Lock
First, you'll need to initialize a new
Auth0Lock object, and provide it with your Auth0 client ID (the unique client ID for each Auth0 application, which you can get from the management dashboard) and your Auth0 domain (for example
2. Authenticating and Getting User Info
Next, listen using the
on method for the
authenticated event. When the event occurs, use the
accessToken which was received to call the
getUserInfo method and acquire the user's profile information (as needed).
You can then manipulate page content and display profile information to the user (for example, displaying their name in a welcome message).
3. Showing Lock
Here you're showing the Lock widget after the user clicks a login button; you can just as easily show Lock automatically when arriving at a page by just using
lock.show(); on page load.
This will show the Lock widget, and paired with the above, you're now ready to handle logins!
You can use Lock's Passwordless Mode to allow users to authenticate using just an email or mobile number. They will receive the code and then return to input it, or click the link, and they can be authenticated without remembering a password.
In Lock v11, in order to implement Passwordless Mode, you initialize Lock in a slightly different manner, with
Auth0LockPasswordless rather than with
Additionally, Lock's Passwordless Mode has a couple of configuration options that are unique to it.
In order to indicate which connection type you would like, you initialize Lock with the
allowedConnections option with either
sms as the value:
If you choose to use
passwordlessMethod option, which takes values of
SSO with embedded authentication
Apps with embedded login must meet two criteria in order to have SSO.
- Both of the applications attempting SSO must be first-party applications. SSO with third party applications will not work.
- 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.
Error Codes and Descriptions
When Lock v11 is used for embedded login, it employs the /co/authenticate endpoint, which has the following errors.
|400||invalid_request||Invalid request body. All and only of client_id, credential_type, username, otp, realm are required.|
|401||unauthorized_client||Cross origin login not allowed.|
|400||unsupported_credential_type||Unknown credential type parameter.|
|400||invalid_request||Unknown realm non-existent-connection.|
|403||access_denied||Invalid user credentials.|
|403||access_denied||Wrong email or password.|
|401||password_leaked||This login attempt has been blocked because the password you're using was previously disclosed through a data breach (not in this application).|
|429||too_many_attempts||Your account has been blocked after multiple consecutive login attempts. We’ve sent you an email with instructions on how to unblock it.|
|429||too_many_attempts||We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.|
In addition, you can also get a generic 403 error without an
error_description property. The response body would just include something similar to the following:
The below widget displays brief examples of implementing Auth0 in several ways: Lock as a modal "popup" widget, Lock embedded inline in a div, Lock Passwordless, a custom UI with Auth0.js, and a simple link using the API.
This document has shown how to use Lock 11 within a Single-Page Application (SPA). Take a look at the following resources to see how Lock can be used with other kinds of web apps, or how it can be customized for your needs: