Simple authentication middleware for integrating Auth0 with Express-based applications.
⚠️ Warning! This is a release candidate of a new major version of
express-auth0-simple! Some things may not work properly. Install
email@example.com the latest stable version!
This NodeJS package abstracts away most of the boilerplate code needed to integrate a NodeJS web application with the oauth authentication provider Auth0.
The code is based on Auth0's own setup guide and should work fine with any application using versions of the Express framework in the 4.x.x version range.
This package is written in ES6 but transpiles down to ES5 or whatever subset of ES6 your runtime supports at installation time.
Here is a quickstart guide on how to setup this middleware.
Add this package to your NodeJS project:
npm install --save express-auth0-simple
The package is typically used wherever you configure your express middleware (becase that's what it is). This is normally in the main
index.js file for small projects.
For this middleware to work you'll need to make sure your express app has session and cookie functionality. You might have this functionality already, but if not you can use these middleware to provide this:
cookie-parser(we've tested against version
express-session(we've tested against version
You'll also need to install passport-js (
passport, we've tested against version
So that your app can authenticate with Auth0, you'll need to provide your Auth0 client credentials. You need to provide your Auth0 Client ID, your Auth0 Client Secret and your Auth0 Domain. These values differ from app to app and you can find the values for your app in its settings page in the dashboard.
The easiest secure way of supplying these credentials to your app is via environment variables and this package will do that by default. Make sure the following environment variables have been set and are accessible to the process running the app:
You can also set these values via the
auth0Options argument of the middleware constructor, but if you are doing this it is highly recommended that these are not stored in source code.
You'll also need to set your client's
callbackURL. This is not automatically loaded by default, so you'll have to pass this yourself in the
auth0Options argument of the middleware constructor, along with any other additional options supported by Auth0.
// ES5var expressAuth0Simple = ;var passport = ;// you might need these middleware aswellvar cookieParser = ;var session = ;
// ES6;;// you might need these middleware aswell;;
Configure dependent middleware
// register cookie and session middlewaresapp;app;// register passportjs middlewaresapp;app;
Make sure your Auth0 environment variables are set before you do this, or provide the Auth0 config as arguments to the middleware constructor.
// ES5var auth =callbackURL: '/auth/callback';
// ES6let auth =callbackURL: '/auth/callback';
Attach the Auth0 callback handler to whatever route you'd like this to be mounted on.
// this is the login routeapp;
Protect your stuff
You can either protect your whole app from unauthenticated access or just specific routes:
// any additional routes declared below this point require login to accessapp;
// only this route requires login to accessapp;
You can log out an authenticated user during any request by calling
The middleware constructor also supports a second argument, which if provided should be an object with either of the following keys:
loginPath- the URL a user goes to to login (this is set to the Auth0 callback URL by default but can be changed if needed). Unauthenticated requests to protected routes will be redirected to this URL, so make sure it's correct if you override it.
failurePath- the URL a user is redirected to if their authentication attempt fails. This is also set to the Auth0 callback URL by default. Unlike
loginPath, changing it will not cause any problems as long as the page redirected to is publicly accessible. This can be used for you to show a custom 'forbidden' page.