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 install 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.1.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:   'foo@bar.com',
      password:   'blabla'
    }, function (err) {
      console.log(err.message);
    });
  });

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.

Change Password (database connections):

  $('.change_password').click(function () {
    auth0.changePassword({
      connection: 'db-conn',
      username:   'foo@bar.com',
      password:   'blabla' // new password
    }, function (err, resp) {
      console.log(err.message);
    });
  });

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:     'foo@bar.com',
  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-2014 Auth0 Inc.

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.