Auth0 Web

This is a wrapper around Auth0.js that favors convention over configuration. Using it on Single-Page Application (SPA) frameworks/libraries like Angular, React, Vue.js, and Aurelia is quite easy.

Installation

First, you need to install it with NPM:

npm i auth0-web

Instatiation/Configuration

Then, you have to import the main class in your code and create one or more Auth0 clients:

import Auth0Web from 'auth0-web';

const auth0Client = new Auth0Web({
  domain: 'bk-samples.auth0.com',
  audience: 'https://contacts.digituz.com.br',
  clientID: '8a7myyLd6leG0HbOhMPtLaSgZ2itD3gK',
  redirectUri: 'http://localhost:3000/callback',
  responseType: 'token id_token',
  scope: 'openid get:contacts post:contacts delete:contacts'
});

Authentication

To authenticate users, you can either begin a explicit authentication process with the signIn method (the user will be redirected to the login page):

// you can initiate the authentication process
auth0Client.signIn();

Or you can try to silently authenticate the user:

// or you can check if there is a session on the IdP
auth0Client.checkSession();

If you follow the explicit authentication, you will need to use parseHash to fetch the token return by Auth0.

Public Methods

By the time of writing, this are the public methods available on Auth0Web instances:

checkSession

The checkSession method initiates the silent authentication. If it succeeds, it loads the session with data (access_token).

clearSession

The clearSession method removes all user data from memory (e.g. accessToken and profile).

constructor

The constructor allows developers to configure new instances. Properties like domain, audience, and scope can only be defined through this method.

getProfile

The getProfile method will return an object with user data. For example, this object will contain name, picture, email, etc.

getAccessToken

If available, getAccessToken will return to the developer an accessToken. With this token, the developer can consume, for example, resources from a server.

getProperties

The getProperties gives you access to the properties that you used when configuring your instance.

isAuthenticated

The isAuthenticated simply checks if there is an accessToken available and return a boolean based on it.

parseHash

The parseHash is used to fetch, from the callback URL, tokens returned by Auth0. If this method finds tokens in the URL, it will load the user profile and load everything in memory. Who can access these data will depend on how you develop your application.

signIn

The signIn method initialises the explicit authentication process. That is, when called, this function will redirect users to the Auth0 login page where they will have the chance to choose a identity provider or input their credentials (username and password).

signOut

The signOut method redirects users to Auth0 server to invalidate their sessions then redirect users back to your app.

subscribe

The subscribe method enables developers to subscribe listeners to the authentication state. These listeners will be called in the following situations:

1. when the library finishes loading the user profile;
2. when the signOut method is explicitly called;
3. when the session on Auth0 server goes invalid;

Further Details

By default, this library uses the Implicit Grant flow of OAuth 2.0. However, developers looking forward to use the Authorization Code Grant flow can still use this library by passing oauthFlow: AUTHORIZATION_CODE, alongside with the other properties, to the Auth0Web constructor.

Development Tips

You can use the npm-link feature to test new versions of this package locally. After configuring it, you will have to update the dist package with the new code. This can be done as shown here:

tsc -p ./ --outDir dist/

License

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