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.

Selecting the connection in Auth0 for multiple login options

Auth0 allows you to offer your users multiple ways of authenticating. This is especially important with SaaS, multitenant apps in which a single app is used by many different organizations, each one potentially using different systems: LDAP, Active Directory, Google Apps, or username/password stores.

Selecting the appropriate Identity Providers from multiple options is called "Home Realm Discovery". A pompous name for a simple problem.

Option 1: programmatically

When you initiate an authentication transaction with Auth0 you can optionally send a connection parameter. This value maps directly with any connection defined in your dashboard.

If using the Lock, this is as simple as writing:

auth0.show({connections: ['YOUR_CONNECTION']});

Notice that this is equivalent of just navigating to:


There are multiple practical ways of getting the connection value. Among the most common ones:

  • You can use vanity URLs: https://{connection}.yoursite.com or https://www.yoursite.com/{connection}
  • You can just ask the user to pick from a list (notice there's an API to retrieve all connections available)

These two methods assume it is acceptable for your app to disclose the names of all companies you are connected to. Sometimes this is not the case.

  • You could use non-human-readable connection names and use some external mechanism to map these to users (e.g. through a primary verification, out of band channel for example).

Option 2: using email domains with Lock

The Lock has built in functionality for identity provider selection. For social connections it will show logos for all those enabled in that particular app.

An additional feature in the Lock is the use of email domains as a way of routing authentication requests. Enterprise connections in Auth0 can be mapped to domains. For example, when configuring an ADFS or a SAML-P identity provider:

If a connection has this setup, then the password textbox gets disabled automatically when typing an e-mail with a mapped domain:

In the example above the domain companyx.com has been mapped to an enterprise connection.

Notice that you can associate multiple domains to a single connection.

Option 3: adding custom buttons to Lock

Using Lock's support for customization and extensibility it's also possible to add buttons for your Custom Social or Enterprise Connections. The following example (written in jQuery) adds a button for Azure AD to Lock:

var lock = new Auth0Lock(cid, domain);
lock.once('signin ready', function() {
  var link = $('<a class="a0-zocial a0-waad" href="#">' +
    '<span>Login with Fabrikam Azure AD</span></a>');
  link.on('click', function() {
      connection: 'fabrikamdirectory.onmicrosoft.com'
    return false;

  $('.a0-iconlist', this.$container)

  connections: ['facebook', 'google-oauth2', 'windows-live']

This is useful when you want to give users a consistent login experience where they click on the connection they want to use.

Lock's stylesheet contains the following provider icons which can be used when adding custom buttons: