auth0-js

What is auth0-js?

The auth0-js package is a JavaScript client library for integrating Auth0 authentication and authorization services into web applications. It provides a variety of methods for handling user authentication, managing user sessions, and interacting with Auth0's API.

What are auth0-js's main functionalities?

User Authentication

This feature allows you to authenticate users by redirecting them to the Auth0 login page. The code sample demonstrates how to initialize the Auth0 client and trigger the authentication process.

const auth0 = new auth0.WebAuth({
  domain: 'YOUR_AUTH0_DOMAIN',
  clientID: 'YOUR_CLIENT_ID'
});

auth0.authorize({
  redirectUri: 'YOUR_CALLBACK_URL',
  responseType: 'token id_token',
  scope: 'openid profile email'
});

Handling Authentication Callback

This feature handles the authentication callback after the user has logged in. The code sample shows how to parse the URL hash to extract authentication tokens.

auth0.parseHash((err, authResult) => {
  if (authResult && authResult.accessToken && authResult.idToken) {
    window.location.hash = '';
    // Save the tokens in local storage or a cookie
  } else if (err) {
    console.error('Error parsing hash:', err);
  }
});

User Logout

This feature allows you to log out users from the application. The code sample demonstrates how to trigger the logout process and redirect the user to a specified URL.

auth0.logout({
  returnTo: 'YOUR_RETURN_URL',
  clientID: 'YOUR_CLIENT_ID'
});

Silent Authentication

This feature allows you to silently authenticate users without redirecting them to the login page. The code sample shows how to check the user's session and obtain new tokens if needed.

auth0.checkSession({}, (err, authResult) => {
  if (err) {
    console.error('Error during silent authentication:', err);
  } else {
    // Use the authResult to get new tokens
  }
});

Other packages similar to auth0-js

passport

Passport is a popular authentication middleware for Node.js. It provides a wide range of authentication strategies, including OAuth, OpenID, and more. Unlike auth0-js, which is specific to Auth0, Passport is more flexible and can be used with various authentication providers.

firebase-auth

Firebase Authentication provides backend services for easy use of authentication in web and mobile apps. It supports various authentication methods like email/password, phone, and social providers. Compared to auth0-js, Firebase Authentication is part of the larger Firebase platform, offering more integrated services.

README

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

Auth0.js is a client-side library for Auth0. It allows you to trigger the authentication process and parse the JWT (JSON web token) with just the Auth0 clientID. Once you have the JWT you can use it to authenticate requests to your http API and validate the JWT in your server-side logic with the clientSecret.

Example

The example directory has a ready-to-go app. In order to run it you need node installed, then execute npm run example from the root of this project.

Usage

Take auth0.js or auth0.min.js from the build directory and import it to your page.

If you are using browserify install with npm i auth0.js.

Note: I use jQuery in these examples but auth0.js doesn't need jquery and you can use anything.

Initialize:

Construct a new instance of the Auth0 client as follows:

<script src="http://cdn.auth0.com/w2/auth0-2.0.5.js"></script>
<script type="text/javascript">
  var auth0 = new Auth0({
    domain:       'mine.auth0.com',
    clientID:     'dsa7d77dsa7d7',
    callbackURL:  'http://my-app.com/callback',
    callbackOnLocationHash: true
  });

  //...
</script>

Login:

Trigger the login on any of your active identity provider as follows:

  //trigger login with google
  $('.login-google').click(function () {
    auth0.login({
      connection: 'google-oauth2'
    });
  });

  //trigger login with github
  $('.login-github').click(function () {
    auth0.login({
      connection: 'github'
    });
  });

  //trigger login with an enterprise connection
  $('.login-github').click(function () {
    auth0.login({
      connection: 'contoso.com'
    });
  });

  //trigger login with a db connection
  $('.login-dbconn').click(function () {
    auth0.login({
      connection: 'db-conn',
      username:   $('.username').val(),
      password:   $('.password').val(),
    });
  });

  //trigger login with a db connection and avoid the redirect (best experience for SPA)
  $('.login-dbconn').click(function () {
    auth0.login({
      connection: 'db-conn',
      username:   $('.username').val(),
      password:   $('.password').val(),
    },
    function (err, profile, id_token, access_token) {
      // store in cookies
    });
  });
  
  //trigger login popup with google
  $('.login-google-popup').click(function (e) {
    e.preventDefault();
    auth0.login({
      connection: 'google-oauth2',
      popup: true,
      popupOptions: {
        width: 450,
        height: 800
      }
    }, function(err, profile, id_token, access_token, state) {
      if (err) {
        alert("something went wrong: " + err.message);
        return;
      }
      alert('hello ' + profile.name);
    });
  });

Processing the callback

Redirect Mode

Once you have succesfully authenticated, Auth0 will redirect to your callbackURL with a hash containing an access_token and the jwt (id_token). You can parse the hash and retrieve the full user profile as follows:

  $(function () {
    var result = auth0.parseHash(window.location.hash);

    //use result.id_token to call your rest api

    if (result && result.id_token) {
      auth0.getProfile(result.id_token, function (err, profile) {
        alert('hello ' + profile.name);
      });
    } else if (result && result.error) {
      alert('error: ' + result.error);
    }
  });

Or just parse the hash (if loginOption.scope is not openid profile, then the profile will only contains the user_id):

  $(function () {
      var result = auth0.parseHash(window.location.hash);
      if (result && result.profile) {
        alert('your user_id is: ' + result.profile.sub);
        //use result.id_token to call your rest api
      }
    });
  });

If there is no hash, result will be null. It the hash contains the jwt, the profile field will be populated.

Popup Mode

While using this mode, the result will be passed as the login method callback.

  auth0.login({ popup: true }, function(err, profile, id_token, access_token, state) {
    if (err) {
      // Handle the error!
      return;
    }
    
    //use id_token to call your rest api
    alert('hello ' + profile.name);
  });
});

Sign up (database connections):

If you use Database Connections you can signup as follows:

  $('.signup').click(function () {
    auth0.signup({
      connection: 'db-conn',
      username:   '[e-mail]',
      password:   'blabla'
    }, function (err) {
      console.log(err.message); ///this could be something like "email is required"
    });
  });

After a succesful login it will auto login the user. If you do not want to automatically login the user you have to pass the option auto_login: false.

Delegation Token Request

You can obtain a delegation token specifying the ID of the target client (targetClientId), the id_token and, optionally, an object (options) in order to include custom parameters like scope:

var targetClientId = "{TARGET_CLIENT_ID}";
var id_token = "{USER_ID_TOKEN}";
var options = {
  "scope": "openid profile"		    // default: openid
};

auth0.getDelegationToken(targetClientId, id_token, options, function (err, delegationResult) {
	// Call your API using delegationResult.id_token
});

Validate User

You can validate a user of a specific connection with his username and password:

auth0.validateUser({
  connection:   'db-conn',
  username:     '[e-mail]',
  password:     'blabla'
}, function (err, valid) { });

Develop

Run grunt dev and point your browser to http://localhost:9999/test_harness.html to run the test suite.

Run grunt test if you have PhantomJS installed.

Do you have issues in some browser? Ask us guidance to test in multiple browsers!

Publishing a new version

Use:

$ mversion patch -m "v%s"
$ git push origin master --tags
$ npm publish

Browser Compatibility

We are using BrowserStack and our own CI server to run the test suite on multiple browsers on every push.

License

The MIT License (MIT)

Copyright (c) 2013 AUTH10 LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.