Lock

Auth0 is an authentication broker that supports social identity providers as well as enterprise identity providers such as Active Directory, LDAP, Google Apps, Salesforce.

Install

From CDN

<!-- Latest patch release (recommended for production) -->
<script src="http://cdn.auth0.com/js/lock/10.0.0/lock.min.js"></script>

From bower

bower install auth0-lock

<script src="bower_components/auth0-lock/build/lock.min.js"></script>

From npm

npm install auth0-lock

After installing the auth0-lock module, you'll need bundle it up along with all of its dependencies. We have examples for browserify and webpack.

If you are targeting mobile audiences, it's recommended that you add:

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>

API

new Auth0Lock(clientID, domain, options)

Initializes a new instance of Auth0Lock configured with your application clientID and your account's domain at Auth0. You can find this information at your application settings.

clientId {String}: Your application clientId in Auth0.
domain {String}: Your Auth0 domain. Usually your-account.auth0.com.
options {Object}: Allows to customize the dialog's appearance and behavior. See below for the details.

Example

var clientId = "YOUR_AUTH0_APP_CLIENTID";
var domain = "YOUR_DOMAIN_AT.auth0.com";
var lock = new Auth0Lock(clientId, domain);

lock.on("authenticated", function(authResult) {
  lock.getProfile(authResult.idToken, function(error, profile) {
    if (error) {
      // Handle error
      return;
    }

    localStorage.setItem("idToken", authResult.idToken);
    localStorage.setItem("profile", JSON.stringify(profile));

    // Update DOM
  });
});

getProfile(idToken, callback)

Once the user has logged in and you are in possesion of and id token, you can obtain the profile with getProfile.

idToken {String}: User id token.
callback {Function}: Will be invoked after the user profile been retrieved.

Example

lock.getProfile(idToken, function(error, profile) {
  if (!error) {
    alert("hello " + profile.name);
  }
});

on(event, callback)

Lock will emit events during its lifecycle.

show: emitted when Lock is shown. Has no arguments.
hide: emitted when Lock is hidden. Has no arguments.
unrecoverable_error: emitted when there is an unrecoverable error, for instance when no connection is available. Has the error as the only argument.
authenticated: emitted after a successful authentication. Has the authentication result as the only argument.
authorization_error: emitted when authorization fails. Has error as the only argument.

Customization

The appearance of the widget and the mechanics of authentication can be customized with an options object which has one or more of the following properties. Each method that opens the dialog can take an options object as its first argument.

UI options

allowedConnections {Array}: List of connection that will be available to perform the authentication. It defaults to all enabled connections.
autoclose {Boolean}: Determines whether or not the Lock will be closed automatically after a successful sign in. If the Lock is not closable it won't be closed even if this option is set to true. Defaults to false.
autofocus {Boolean}: Determines whether or not the first input on the screen, that is the email or phone number input, should have focus when the Lock is displayed. Defaults to false when a container option is provided or the Lock is being render on a mobile device. Otherwise it defaults to true.
avatar {Object}: Determines whether or not an avatar and a user name should be displayed on the Lock's header once an email or username has been entered and how to obtain it. By default avatars are fetched from Gravatar. Supplying null will disable the functionality. To fetch avatar from other provider see below.
container {String}: The id of the html element where the Lock will be rendered. This makes the Lock appear inline instead of in a modal window.
language {String}: Specifies the language of the widget. Defaults to "en".
languageDictionary {Object}: Allows to customize every piece of text displayed in the Lock. Defaults to {}. See below Language Dictionary Specification for the details.
closable {Boolean}: Determines whether or not the Lock can be closed. When a container option is provided its value is always false, otherwise it defaults to true.
popupOptions {Object}: Allows to customize the location of the popup in the screen. Any position and size feature allowed by window.open is accepted. Defaults to {}.
rememberLastLogin {Boolean}: Determines whether or not to show a screen that allows you to quickly log in with the account you used the last time. Defaults to true.

Theming options

Theme options are grouped in the theme property of the options object.

var options = {
  theme: {
    logo: "https://example.com/assets/logo.png",
    primaryColor: "green"
  }
};

logo {String}: Url for an image that will be placed in the Lock's header. Defaults to Auth0's logo.
primaryColor {String}: Defines the primary color of the Lock, all colors used in the widget will be calculated from it. This option is useful when providing a custom logo to ensure all colors go well together with the logo's color palette. Defaults to "#ea5323".

Authentication options

Authentication options are grouped in the auth property of the options object.

var options = {
  auth: {
   params: {param1: "value1"},
   redirect: true,
   redirectUrl: "some url",
   responseType: "token",
   sso: true
  }
};

params {Object}: Specifies extra parameters that will be sent when starting a login. Defaults to {}.
redirect {Boolean}: When set to true, the default, redirect mode will be used. Otherwise, popup mode is chosen. See below for more details.
redirectUrl {String}: The url Auth0 will redirect back after authentication. Defaults to the empty string "" (no redirect URL).
responseType {String}: Should be set to "token" for Single Page Applications, and "code" otherwise. Defaults to "code" when callbackURL is provided, and to "token" otherwise.
sso {Boolean}: Determines whether Single Sign On is enabled or not. Defaults to true.

Social options

socialButtonStyle {String}: Determines the size of the buttons for the social providers. Possible values are "big" and "small". The default style depends on the connections that are available:
- If only social connections are available, it will default to "big" when there are 5 connections at most, and default to "small" otherwise.
- If connections from types other than social are also available, it will default to "big" when there are 3 social connections at most, and default to "small" otherwise.

Database options

additionalSignUpFields {Array}: Allows to provide extra input fields during sign up. See below more for details. Defaults to [].
allowLogin {Boolean}: When set to false the widget won't display the login screen. This is useful if you want to use the widget just for sign ups (the login and sign up tabs in the sign up screen will be hidden) or to reset passwords (the back button in the forgot password screen will be hidden). In such cases you may also need to specify the initialScreen, allowForgotPassword and allowSignUp options. It defaults to true.
allowForgotPassword {Boolean}: When set to false hides the "Don't remember your password?" link in the login screen, making the forgot password screen unreachable. Defaults to true. Keep in mind that if you are using a database connection with a custom database which doesn't have a change password script the forgot password screen won't be available.
allowSignUp {Boolean}: When set to false hides the login and sign up tabs in the login screen, making the sign up screen unreachable. Defaults to true. Keep in mind that if the database connection has sign ups disabled or you are using a custom database with coesn't have a create script, then the sign up screen won't be available.
defaultDatabaseConnection {String}: Specifies the database connection that will be used when there is more than one available.
initialScreen {String}: Name of the screen that will be shown when the widget is opened. Valid values are "login", "signUp", and "forgotPassword". If this option is left unspecified, the widget will pick the first screen that is available from the previous list.
loginAfterSignUp {String}: Determines whether or not the user will be automatically signed in after a successful sign up. Defaults to true.
forgotPasswordLink {String}: URL for a page that allows the user to reset her password. When set to a non-empty string, the user will be linked to the provided URL when clicking the "Don't remember your password?" link in the login screen.
mustAcceptTerms {Boolean}: When set to true displays a checkbox input along the terms and conditions that must be checked before signing up. The terms and conditions can be specified via the languageDictionary option, see the example below. Defaults to false.
prefill {Object}: Allows to set the initial value for the email and/or username inputs, e.g. {prefill: {email: "someone@auth0.com", username: "someone"}}. When omitted no initial value will be provided.
signUpLink {String}: URL for a page that allows the user to sign up. When set to a non-empty string, the user will be linked to the provided URL when clicking the sign up tab in the login screen.
usernameStyle {String}: Determines what will be used to identify the user. Possible values are "username" and "email". Defaults to "email".

Enterprise options

defaultEnterpriseConnection {String}: Specifies the enterprise connection which allows to login using an username and a password that will be used when there is more than one available or there is a database connection. If a defaultDatabaseConnection is provided the database connection will be used and this option will be ignored.

Example

var options = {
  container: "myContainer",
  closable: false,
  languageDictionary: {
    signUpTerms: "I agree to the <a href='/terms' target='_new'>terms of service</a> and <a href='/privacy' target='_new'>privacy policy</a>.",
    title: "My Company",
  },
  autofocus: false
};

Other options

assetsUrl {String}: Will be used as the assets base url. Defaults to Auth0's the CDN url when domain has the format *.auth0.com. Otherwise, it defaults to domain.

Language Dictionary Specification

A language dictionary is an object that allows you to customize every piece of text the Lock needs to display. For instance, the following code will change the title displayed in the header and the placeholder for the email field.

var options = {
  languageDictionary: {
    emailInputPlaceholder: "please enter you email",
    title: "My Company"
  },
};

Additional sign up fields

Extra input fields can be added to the sign up screen with the additionalSignUpFields option. Every input must have a name and a placeholder, and an icon url can also be provided. Also, the initial value can be provided with the prefill option, which can be a string with the value or a function that obtains it. Other options depend on the type of the field, which is defined via the type option and defaults to "text".

The new fields are rendered below the regular sign up input fields in the order they are provided.

Text field

A validator function can also be provided.

var options = {
  additionalSignUpFields: [{
    name: "address",
    placeholder: "enter your address",
    // The following properties are optional
    icon: "https://example.com/assests/address_icon.png",
    prefill: "street 123",
    validator: function(address) {
      return {
         valid: address.length >= 10,
         hint: "Must have 10 or more chars" // optional
      };
    }
  }]
}

Select field

To specify a select field type: "select" needs to be provided along with the options property.

var options = {
  additionalSignUpFields: [{
    type: "select",
    name: "location",
    placeholder: "choose your location",
    options: [
      {value: "us", label: "United States"},
      {value: "fr", label: "France"},
      {value: "ar", label: "Argentina"}
    ],
    // The following properties are optional
    icon: "https://example.com/assests/location_icon.png",
    prefill: "us"
  }]
}

The options and the prefill value can be provided through a function.

var options = {
  additionalSignUpFields: [{
    type: "select",
    name: "location",
    placeholder: "choose your location",
    options: function(cb) {
      // obtain options, in case of error you call cb with the error in the
      // first arg instead of null
      cb(null, options);
    },
    icon: "https://example.com/assests/location_icon.png",
    prefill: function(cb) {
      // obtain prefill, in case of error you call cb with the error in the
      // first arg instead of null
      cb(null, prefill);
    }
  }]
}

Avatar provider

Lock can show avatars fetched from anywhere. A custom avatar provider can be specified with the avatar option by passing an object with the keys url and displayName. Both properties are functions that take an email and a callback function.

var options = {
  avatar: {
    url: function(email, cb) {
      // obtain url for email, in case of error you call cb with the error in
      // the first arg instead of null
      cb(null, url);
    },
    displayName: function(email, cb) {
      // obtain displayName for email, in case of error you call cb with the
      // error in the first arg instead of null
      cb(null, displayName);
    }
  }
};

Popup mode

A popup window can be displayed instead of redirecting the user to a social provider website. While this has the advantage of preserving page state, it has some issues. Often times users have popup blockers that prevent the login page from even displaying. There are also known issues with mobile browsers. For example, in recent versions of Chrome on iOS, the login popup does not get closed properly after login. For these reasons, we encourage developers to avoid this mode, even with Single Page Apps.

If you nevertheless decide to use it, you can activate popup mode by passing the option auth: {redirect: false} when constructing Auth0Lock.

var clientId = "YOUR_AUTH0_APP_CLIENTID";
var domain = "YOUR_DOMAIN_AT.auth0.com";
var options = {
  auth: {
    redirect: false
  }
};

var lock = new Auth0LockPasswordless(clientId, domain, options,
  function(error, result) {
    // Will only be executed after an attempt to login has been made (contrast
    // this with redirect mode in which the function is always executed)
});

More information can be found in Auth0's documentation.

Browser Compatibility

We ensure browser compatibility in Chrome, Safari, Firefox and IE >= 10. We currently use zuul along with Saucelabs to run integration tests on each push.

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.

rafalwrzeszcz/lock

Lock

Install

API

new Auth0Lock(clientID, domain, options)

Example

getProfile(idToken, callback)

Example

on(event, callback)

Customization

UI options

Theming options

Authentication options

Social options

Database options

Enterprise options

Example

Other options

Language Dictionary Specification

Additional sign up fields

Text field

Select field

Avatar provider

Popup mode

Browser Compatibility

Issue Reporting

Author

License