Docs

Node.js

View on Github

Node.js

Gravatar for andres.aguiar@auth0.com
By Andres Aguiar
Auth0

This tutorial demonstrates how to add user login, logout, and profile to a Node.js Express application. We recommend you to Log in to follow this quickstart with examples configured for your account.

I want to explore a sample app

2 minutes

Get a sample configured with your account settings or check it out on Github.

View on Github
System requirements: NodeJS 4.3 or higher | Express 4.16

New to Auth? Learn How Auth0 works, how it integrates with Regular Web Applications and which protocol it uses.

Configure Auth0

Get Your Application Keys

When you signed up for Auth0, a new application was created for you, or you could have created a new one.

You will need some details about that application to communicate with Auth0. You can get these details from the Application Settings section in the Auth0 dashboard.

You need the following information:

  • Client ID
  • Domain

If you download the sample from the top of this page these details are filled out for you.

If you have more than one application in your account, the sample comes with the values for your Default App.

App Dashboard

Configure Callback URLs

A callback URL is a URL in your application where Auth0 redirects the user after they have authenticated.

You need to whitelist the callback URL for your app in the Allowed Callback URLs field in your Application Settings. If you do not set any callback URL, your users will see a mismatch error when they log in.

If you are following along with the sample project you downloaded from the top of this page, you should set the Callback URL to http://localhost:3000/callback.

Configure Logout URLs

A logout URL is a URL in your application that Auth0 can return to after the user has been logged out of the authorization server. This is specified in the returnTo query parameter.

You can set the logout URL for your app in the Allowed Logout URLs field in your Application Settings. If you don't set a logout URL, your users will be unable to log out of the application and will get an error.

Configure Node.js to use Auth0

Create the .env file

Create the .env file in the root of your app and add your Auth0 variables and values to it.

Do not put the .env file into source control. Otherwise, your history will contain references to your client secret.

If you are using git, create a .gitignore file (or edit your existing one, if you have one already) and add .env to it. The .gitignore file tells source control to ignore the files (or file patterns) you list. Be careful to add .env to your .gitignore file and commit that change before you add your .env.

Install the dependencies

To get started, install the following dependencies.

  • passport - an authentication middleware for Node.js
  • passport-auth0 - an Auth0 authentication strategy for Passport
  • express-session - a middleware to manage sessions
  • dotenv - a module to load environment variables from a .env file

Configure express-session

In app.js, include the express-session module and configure it. The secret parameter is a secret string that is used to sign the session ID cookie. Please use a custom value.

Configure Passport with the application settings

In app.js, include the passport and passport-auth0 modules, and configure Passport to use a new instance of Auth0Strategy with your Auth0 application settings. Use passport.initialize() and passport.session() to initialize Passport with persistent login sessions.

Please make sure these last two commands are in your code after the application of the express middleware (app.use(session(sess)).

Storing and retrieving user data from the session

In a typical web application, the credentials used to authenticate a user are only transmitted during the login request. If authentication succeeds, a session is established and maintained via a cookie set in the user's browser. Each subsequent request does not contain credentials, but rather the unique cookie that identifies the session.

To support login sessions, Passport serializes and deserializes user instances to and from the session. Optionally, you may want to serialize only a subset to reduce the footprint, i.e., user.id.

Implement login, user profile and logout

In this example, following routes are implemented:

  • /login triggers the authentication by calling Passport's authenticate method. The user is then redirected to the tenant login page hosted by Auth0.
  • /callback is the route the user is returned to by Auth0 after authenticating. It redirects the user to the profile page (/user).
  • /user displays the user's profile.
  • /logout logs the user out of Auth0.

We will use the following routers:

  • routes/auth.js, to handle authentication
  • routes/index.js, to serve the home page
  • routes/users.js, to serve the user profile

Adding the authentication router

Start by creating a new router routes/auth.js to handle authentication.

In the authentication step, make sure to pass the scope parameter with values openid email profile to access email and the other attributes stored in the user profile. This is needed to display the user's information on the profile page.

This tutorial implements logout by closing the local user session and the user's Auth0 session as well. For other implementations, please refer to the logout documentation.

Middleware to protect routes

Create a secured middleware to protect routes and ensure they are only accessible if logged in.

If the user is not logged in, the requested route will be stored in the session and the user will be redirected to the login page. Upon successful login, the user will be redirected to the previously requested URL (see callback route above).

Create the user profile route

The /user route (the user's profile) should only be accessible if the user is logged in. Use the secured middleware to secure the route.

Index route

If you don't have one yet, create an index route to serve the homepage.

Making the user available in the views

In the views and layouts, it is often necessary to conditionally render content depending on if a user is logged in or not. Other times, the user object might be necessary in order to customize the view.

Create a middleware lib/middleware/userInViews.js for this purpose.

Including the routers and userInViews middleware

Include the new routers and the userInViews middleware in your app:

Use locals.user, as implemented in the middleware, to customize the views. For example, we can use it to conditionally render links related to the user session in the layout.

Implement the user profile view

Create a views/user.pug template. Use locals.user to access the user data in the session.

See it in action

Install the dependencies, start your app and point your browser to http://localhost:3000. Follow the Log In link to log in or sign up to your Auth0 tenant. Upon successful login or signup, you should be redirected to the user's profile page.

login page

Use Auth0 for FREE