--- title: "Auth0’s express-OpenID-connect SDK: the Easiest Way to Do Authentication on Node.js" description: "Learn how to add OpenID Connect authentication to your Express apps, using our just released express-OpenID-connect SDK" authors: - name: "Vittorio Bertocci" url: "https://auth0.com/blog/authors/vittorio-bertocci/" date: "Sep 17, 2020" category: "Developers,Deep Dive,OpenID" tags: ["express-openid-connect", "node-js", "openid-connect", "authentication"] url: "https://auth0.com/blog/auth0-s-express-openid-connect-sdk/" --- # Auth0’s express-OpenID-connect SDK: the Easiest Way to Do Authentication on Node.js **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 — 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 — 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://.auth0.com CLIENT_ID= BASE_URL=https://localhost SECRET= ``` 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 — 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 — 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 — 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!