Auth0 Login Widget v2

The Auth0 Login Widget makes it easy to integrate SSO in your app. You won't have to worry about:

  • Having a professional looking login dialog that displays well on any resolution and device.
  • Finding the right icons for popular social providers.
  • Remembering what was the identity provider the user chose the last time.
  • Solving the home realm discovery challenge with enterprise users (i.e.: asking the enterprise user the email, and redirecting to the right enterprise identity provider).
  • Implementing a standard sign in protocol (OpenID Connect / OAuth2 Login)

Including the Login Widget on your page

Add the script tag to your page to get started with Auth0 Login Widget.

<script src="https://cdn.auth0.com/w2/auth0-widget-3.0.min.js"></script>

Playground

There are different ways of integrating Auth0 in your site. Below, some of them with a preview and a code snippet to copy paste.

This is how it will look on a browser...

Auth0 JavaScript libraries are Open Source: https://github.com/auth0/widget https://github.com/auth0/auth0.js

Single Page Applications

You can handle the authorization process client-side as follows:

<script type="text/javascript">
    var widget = new Auth0Widget({
        domain:                 'YOUR_NAMESPACE',
        clientID:               'YOUR_CLIENT_ID', 
        callbackURL:            'http://YOUR_APP/callback',
        callbackOnLocationHash: true
    });

    var result = widget.parseHash(location.hash);
    if (result) {
        widget.getProfile(result.id_token, function (err, profile) {
            // store result.id_token and profile in local storage or cookie
        });
    }

    widget.signin();
</script>

When callbackOnLocationHash: true is specified, Auth0 will send the response back as a redirect to your site passing the tokens after the hash sign: http://YOUR_APP/callback#access_token=...&id_token=....

Customizing the Widget

The Widget can be customized through the options parameter sent to the signin method.

 Options

  • connections: Array of enabled connections that will be used for the widget. Default: all enabled connections.
  • container: The id of the DIV where the widget will be contained.
  • icon: Icon url. Recommended: 32x32.
  • showIcon: Show/Hide widget icon. Default: false.
  • showForgot: Show/Hide the "Forgot your password?" link. Default: true.
  • showSignup: Show/Hide the "Sign Up" link. Default: true.
  • enableReturnUserExperience: Show the account used last time the user signed in. Default: true.
  • userPwdConnectionName: Specify which Database/AD-LDAP connection should be used with the Email/Password fields. Default: the first Database connection found (if it exists) or the first AD-LDAP connection found.
  • username_style: Specify the format of the username. Options: email or username.

Is there an option that you think would be useful? Just open an issue on GitHub and we'll look into adding it.

This example shows how to work with only specified connections and display the labels in Spanish:

var widget = new Auth0Widget({
    domain:         'YOUR_NAMESPACE',
    clientID:       'YOUR_CLIENT_ID', 
    callbackURL:    'http://YOUR_APP/callback',
    dict:           'es'
});

widget.signin({
    connections:    ['facebook', 'google-oauth2', 'twitter', 'Username-Password-Authentication'],
    icon:           'https://contoso.com/logo-32.png',
    showIcon:       true
},
function () {
  // The Auth0 Widget is now loaded.
});

dict constructor parameter is a string matching the language ('en', 'es', 'it', etc.) or object containing all your customized text labels.

Resulting in:

Sending extra login parameters

You can send extra parameters when starting a login by adding them to the options object. The example below adds a state parameter with a value equal to foo.

widget.signin({
    // ... other options ... 
    state: 'foo'
});

The following parameters are supported: access_token, protocol, request_id, scope and state.

There are other extrar parameters that will depend on the provider. For example, Google allows you to get back a refresh_token only if you explictely ask for access_type=offline. We support sending arbitrary parameters like this:

widget.signin({
    // ... other options ... 
    extraParameters: {
        access_type: 'offline'
    }
});

Note: this would be analogous to trigger the login with https://YOUR_NAMESPACE/authorize?state=foo&access_type=offline&....

 Scope

There are different values supported for scope:

  • scope: 'openid': (default) It will return, not only the access_token, but also an id_token which is a Json Web Token (JWT). The JWT will only contain the user id (sub claim).
  • scope: 'openid profile': If you want the entire user profile to be part of the id_token.
  • scope: 'openid {attr1} {attr2} {attrN}': If you want only specific user's attributes to be part of the id_token (For example: scope: 'openid name email picture').

Signup and Reset

It is also possible to start the widget in the Sign Up mode or Reset Password mode as follows:

widget.signup(/* [same as the .signin method] */);
// or
widget.reset(/* [same as the .signin method] */);

Anatomy of the Auth0 Login Widget

  1. The title of the widget. You can optionally show a 32x32 icon.
  2. The social buttons will be shown if you have at least one social connection enabled.
  3. The Email field will be shown if you have at least one enterprise connection enabled. The Password field will be shown if you have a Database connection.
  4. The Sign Up and Forgot Password links will be shown if you have a Database connection.

How does enterprise SSO work? Consider a user that enters john@fabrikam.com. If there's an enterprise connection with an associated domain "fabrikam.com", then the password field will be hidden. When the user clicks on Sign In, he/she will be redirected to the corresponding identity provider (Google Apps, AD, Windows Azure AD, etc.) where that domain is registered. If the user is already logged in with the Identity Provider, then Single Sign On will happen.

Customize the look and feel

You can apply your own style to the elements. All classes and ids are prefixed with a0- to avoid conflicts with your own stylesheets.

Customizing error messages

You can also customize the error messages that will be displayed on certain situations:

var widget = new Auth0Widget({
    // ... other parameters ... 
    dict: {
        loadingTitle:   'loading...',
        close:          'close',
        signin: {
            wrongEmailPasswordErrorText: 'Custom error message for invalid user/pass.',
            serverErrorText: 'There was an error processing the sign in.',
            strategyEmailInvalid: 'The email is invalid.',
            strategyDomainInvalid: 'The domain {domain} has not been setup.'
        },
        signup: {
            serverErrorText: 'There was an error processing the sign up.',
            enterpriseEmailWarningText: 'This domain {domain} has been configured for Single Sign On and you can\'t create an account. Try signing in instead.'
        },
        reset: {
            serverErrorText: 'There was an error processing the reset password.'
        }
        // wrongEmailPasswordErrorText, serverErrorText, enterpriseEmailWarningText are used only if you have a Database connection
        // strategyEmailInvalid is shown if the email is not valid
        // strategyDomainInvalid is shown if the email does not have a matching enterprise connection
    }
});

These errors will be shown on the widget header: