joey devilla headshot 900px

I’m a Senior Developer Advocate at Auth0, and I like to work on various technologies. I’ve developed software for all sorts of platforms, from CD-ROM and the PalmPilot to my current area of focus, mobile phones, IoT devices, and AI. When I’m not looking for strange new platforms to write software for, I’m playing a strange old instrument — the accordion!

Senior Developer Advocate

Joey deVilla

Learn how to use Auth0 Actions to redirect users to an announcement web page and back to the application (or just redirect them to Rick Astley’s video).

Use Actions to Show Users an Announcement after Logging in (Or Rickroll Them)

37590801?s=460&v=4

A software engineer who dreams about non-electric sheep and autonomous vehicles and likes to champion security.

Software Engineer

Dan Arias

Learn how to use Express and Pug to build a website in Node.js

Build a Website with Node.js and Express

bruno-krebs

I am passionate about developing highly scalable, resilient applications. I love everything from the database, to microservices (Kubernetes, Docker, etc), to the frontend. I find amazing to think about how all pieces work together to provide a fast and pleasurable experience to end users, mainly because they have no clue how complex that "simple" app is.

R&D Content Architect

Bruno Krebs

Learn how to develop RESTful APIs with Node.js and Express while securing it with Auth0.

Node.js and Express Tutorial: Building and Securing RESTful APIs

Learn how to use Passport.js to add user authentication to a web app built with Node.js and Express.

Node.js and Express Authentication Using Passport

andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Learn how to create real-time web applications by using the Server-Sent Events specification.

Developing Real-Time Web Applications with Server-Sent Events

Vittorio

Vittorio Bertocci is a Principal Architect for Auth0. Before Auth0, he had a lengthy career with Microsoft, where Vittorio worked with Fortune 100 and Global 100 companies, including working on Microsoft’s Azure Active Directory team as principal program manager focusing on the developer experience. He contributed to the inception and launch of Microsoft's claims-based platform components (Windows Identity Foundation and ADFS, ADAL and MSAL SDKs, ASP.NET middleware). Vittorio is a well known speaker, educator and published author.

Principal Architect

Vittorio Bertocci

Learn how to add OpenID Connect authentication to your Express apps, using our just released express-OpenID-connect SDK



**TL;DR**: Today, Auth0 announces the release of [`express-openid-connect`](https://github.com/auth0/express-openid-connect), a new Node.js SDK that makes it super easy to add [OpenID Connect](https://auth0.com/docs/protocols/openid-connect-protocol) authentication to your Express apps. You can [install it using `npm`](https://www.npmjs.com/package/express-openid-connect) today.

Since Auth0 relies on open protocols to expose its features, you can use its services from any platform and app type, without requiring any proprietary SDK. Whenever a platform or a dev stack has a good, well-designed SDK, the [Auth0 Quickstarts](https://auth0.com/docs/quickstarts) simply use that &mdash; no need to reinvent the wheel!

When the targeted platform does not have a great experience available, we will often step in and create one. Historically, that’s what we have done for Node.js &mdash; a very special platform for us at Auth0, powering our very own authorization server, our extensibility model, and many of our samples.

About eight years ago, we provided an [Auth0 strategy for Passport.js](https://www.npmjs.com/package/passport-auth0), which has been downloaded more than 2M times and is still going strong. Despite its obvious success, however, our Passport strategy is starting to show its age. For example:

* It requires more code to initialize and use authentication features than is strictly necessary.
* It brings significant dependencies into your app, a burden that many developers might want to avoid.
* It is Auth0 specific, whereas Auth0’s web sign-on function can be easily achieved with pure OpenID Connect.

That’s why we decided to create a new Node.js SDK that is ultra-easy to use, nimble, and standard-based, providing a great experience to Node.js developers, not just when using Auth0, but with any provider that uses OpenID Connect.

## Adding Web Sign-On to a Node.js App Really Fast

Before we get into the library’s architecture, let me just give you a quick taste of what it feels like to use [`express-openid-connect`](https://github.com/auth0/express-openid-connect) to add web sign on to a Node.js web app.
 
Adding `express-openid-connect` to your project is straightforward:

``` bash  
$ npm init -f
$ npm install auth0/express-openid-connect express dotenv 
```

You can initialize the SDK in code or via environment variables. For the latter, the minimal `.env` file would look like the following:

``` bash  
ISSUER_BASE_URL=https://<YOURTENANT>.auth0.com
CLIENT_ID=<YOURCLIENTID>
BASE_URL=https://localhost
SECRET=<LONGRANDOMSTRING>
```

All the `<>` values need to be updated with the details of your tenant app, that you’ll find in the Auth0 Dashboard. In this example, we assume that your Allowed Callbacks URLs include [`https://localhost/callback`](https://localhost/callback) (note, the `SECRET` is not your client secret &mdash; any long random string will do).

A diminutive `server.js` could look like the following:

``` javascript  
const express = require('express');
const { auth } = require('express-openid-connect');
require('dotenv').config();
const app = express();
app.use(auth());
app.get('/', (req, res) => {
  res.send(`hello ${req.oidc.user.name}`);
});
app.set('trust proxy', true);
app.listen(3000, () => console.log('listening at http://localhost:3000'))
```

Note, this isn’t the absolute smallest app with web sign-in that you can write (I tweeted a [much smaller one](https://twitter.com/vibronet/status/1287776298920636421?s=20)), but it still gives an idea of how concise `express-openid-connect` code can be, while remaining perfectly readable. In a nutshell:

* Lines 1-3 pull in dependencies and load `.env`.
* Lines 4-5 initialize `express` and add `express-openid-connect` middleware in the pipeline. That will have the effect to protect every app route with OpenID Connect.
* Lines 6-8 define the behavior of the root route &mdash; showing the name of the authenticated user.
* Lines 9-10 start the app, enabling the use of a proxy.

I could have easily skipped the proxy part, but given that the [SameSite changes make HTTPS mandatory for `SameSite=none` cookies](https://auth0.com/blog/browser-behavior-changes-what-developers-need-to-know/), it’s a good habit to start using HTTPS at development time anyway. See the ["HTTPS in Development" document](https://auth0.com/docs/libraries/secure-local-development) for more detailed instructions.

For our purposes, all you need to do is to install a reverse proxy like Caddy 2* (`$ brew install Caddy` or [https://caddyserver.com/docs/download](https://caddyserver.com/docs/download)) and launch it:

``` bash  
$ caddy reverse-proxy --from localhost:443 --to localhost:3000
```

All you need to do now is to launch your app with `node server.js` and navigate to [https://localhost](https://localhost/). You’ll see the familiar prompt and, once authenticated, the user greeting:

![authPrompt](https://images.ctfassets.net/23aumh6u8s0i/7EjGFggvxs3ZOCctng0XJA/3da0d378b994ad77700b9a642c0495e2/login_prompt)

That’s it! In barely one Word page, I gave you the complete instructions to build an authenticated web app from scratch, including explanations of what the code does and how to run it on HTTPS in `localhost`. Here’s a comparison with the code required by the Auth0 Passport.js strategy to achieve the same functionality:

![Passport Comparison](https://images.ctfassets.net/23aumh6u8s0i/1KVwAZ5Poh1FeUkLwNax4M/c34ea7a9de120d4acb0bd1acf8e33336/3-passportcomparison)

Looks great, but what’s really going on here? Let’s take a deeper look.

## The Architecture of `express-openid-connect`

In a nutshell: `express-openid-connect` is an application-level Express middleware, which implements the OpenID Connect protocol with the purpose of adding and managing authentication for your web application.

The middleware effectively wraps [`node-openid-client`](https://github.com/panva/node-openid-client), an [OpenID Connect certified](https://openid.net/certification/) client for Node.js maintained by our very own [Filip Skokan](https://auth0.com/blog/authors/filip-skokan/), which handles all the protocol concerns. As mentioned, you can use `express-openid-connect` with any OpenID Connect provider, not just Auth0. You’re welcome!

As a middleware, `express-openid-connect` is meant to implement a sign-in for a web application. That means that no matter what protocol flow is selected, the SDK will always want to end up with an `id_token` to validate and ultimately create a session for your web app.

Here’s a diagram describing what happens under the hood when an unauthenticated user attempts to access a protected app route, `/profile`, using the default settings demonstrated in the preceding section.

![login](https://images.ctfassets.net/23aumh6u8s0i/jQrfvs3dBaZDPn2FS2ojs/0d3458ea73357e7cf78f9213568ccfda/4-login)

As we’ve seen, you don’t need to grok all the fine details of that diagram to successfully use the SDK: but it’s a handy reference if you want to know how the standards are used and how the various components of the solution collaborate to achieve route protection and sign on. You can find this and other diagrams in the ["Architecture" section of the `express-openid-connect` documentation](https://github.com/auth0/express-openid-connect/blob/master/ARCHITECTURE.md).

The default OpenID Connect flow used by `express-openid-connect` is `implicit + form_post`, requesting `response_type=id_token` and `response_mode=form_post`. That’s the absolute simplest sign inflow to set up, as it doesn’t require client secrets (the secret you configured was for protecting the session cookie, no backend traffic, or registration required for it).

If, in addition to the `id_token`, you also want to obtain an access token to invoke protected API endpoints, the SDK allows you to choose the code or hybrid flow. All you need to do is to use the SDK config options to override the defaults.

If you want to go beyond the basics, `express-openid-connect` offers a very comprehensive [collection of configuration settings](https://auth0.github.io/express-openid-connect/) that allow you to control every aspect of how authentication occurs, including:

* Fine control over the session behavior (rolling, absolute, transient, or persistent, etc.),

* Fine control over authorization request characteristics (grants, whether to request access tokens for an external API together with the initial request, what scopes to request, etc.).

* Customization of the default routes used by the SDK for triggering authentication, sign out, etc

* ...and a lot more

As you’ve seen, the most common use case is super easy to implement. You initialize the middleware with the essential parameters, add it in the pipeline, and by default, everything is protected. That is to say, any attempt to access a route by an unauthenticated user will trigger the authentication dance.

If you don’t want blanket protection, you can elect to secure individual routes by setting `authRequired` to `false` and applying the `requiresAuth` middleware to individual routes.

Alternatively, you can initiate an authentication operation programmatically from anywhere via the SDK method `login`. If your authorization requirements are more complex, you can easily set up more sophisticated route protection logic. For example, you can configure a given route to be accessible only by users possessing specific claim types and values by using [`claimEquals`](https://auth0.github.io/express-openid-connect/globals.html#claimequals), [`claimInclude`](https://auth0.github.io/express-openid-connect/globals.html#claimincludes), or, for completely custom criteria, [`claimCheck`](https://auth0.github.io/express-openid-connect/globals.html#claimcheck).

The SDK comes with an essential [Express Quickstart](https://auth0.com/docs/quickstart/webapp/express), accompanied by a [sample](https://github.com/auth0-samples/auth0-express-webapp-sample) that shows how to accomplish more advanced tasks, such as obtaining access tokens for API or using and refreshing them when necessary.

## What’s Going to Happen to `passport-auth0`?

The answer is... nothing. Unless someone finds a security bug, that is. [`passport-auth0`](https://github.com/auth0/passport-auth0) is used and loved by many Auth0 customers &mdash; and remains fully supported. There’s no need to rush updates to your existing apps. We will keep fixing bugs and patch them. We plan to stop adding new features to `passport-auth0`, and the bar for the bugs we fix will be tuned accordingly. If you are about to start a new project, we recommend considering using `express-openid-connect`, as it will be our target for all innovation for web sign-in on the Node.js platform for the foreseeable future.

## What’s Next

There are many features we really want to add to `express-openid-connect` (hello, custom session persistence) that didn’t make it in time for this release. We’re already hard at work on those: if you have feedback, wish lists, pet peeves, now it’s the time to hit us up via the [Issues list](https://github.com/auth0/express-openid-connect/issues).

We are also planning to produce a similar SDK for Express APIs, giving Node.js API developers a way to enjoy the same ease of use and lightweight integration we achieved with `express-openid-connect`.

Happy coding!


Auth0’s express-OpenID-connect SDK: the Easiest Way to Do Authentication on Node.js

idee

Software Engineer building with Kotlin and Flutter.

Software Engineer at Busha

Idorenyin Obong

How to configure a Continuous Deployment pipeline utilizing Now.sh, GitHub, and Travis CI to automate your open-source Node.js web apps.

"node-js"