express-openid-connect

Express OpenID Connect

Express.js middleware for OpenID Relying Party (aka OAuth 2.0 Client). Easily add secure and standards-based authentication to Express applications.

This library requires:

• Node v10.13 or higher
• Express v4.16 or higher

Please Note: This library is currently in pre-release status and has not had a complete security review. We do not recommend using this library in production yet. As we move towards early access, please be aware that releases may contain breaking changes. We will be monitoring the Issues queue here for feedback and questions. PRs and comments on existing PRs are welcome!

Table of Contents

• Documentation
• Installation
• Getting Started
• Contributing
• Support + Feedback
• Vulnerability Reporting
• What is Auth0
• License

Documentation

• Our Express Quickstart is the quickest way to get up and running from scratch.
• Use the Examples for common configurations for use cases beyond the basics.
• The API documentation details all configuration options, methods, and data that this library provides.
• You can run the sample application to see how this SDK functions without writing your own integration.

Installation

This library is installed with npm:

npm i express-openid-connect --save

Getting Started

The library needs the following required configuration keys to request and accept authentication. These can be configured in a .env file in the root of your application:

# .env

ISSUER_BASE_URL=https://YOUR_DOMAIN
CLIENT_ID=YOUR_CLIENT_ID
BASE_URL=https://YOUR_APPLICATION_ROOT_URL
APP_SESSION_SECRET=LONG_RANDOM_VALUE

... or in the library initialization:

// index.js

const { auth } = require('express-openid-connect');
app.use(auth({
  issuerBaseURL: 'https://YOUR_DOMAIN',
  baseURL: 'https://YOUR_APPLICATION_ROOT_URL',
  clientID: 'YOUR_CLIENT_ID',
  appSessionKey: 'LONG_RANDOM_STRING'
}));

With this basic configuration, your application will require authentication for all routes and store the user identity in an encrypted and signed cookie.

See the examples for route-specific authentication, custom application session handling, requesting and using access tokens for external APIs, and more.

See the API documentation for additional configuration possibilities and provided methods.

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines

Contributions can be made to this library through PRs to fix issues, improve documentation or add features. Please fork this repo, create a well-named branch, and submit a PR with a complete template filled out.

Code changes in PRs should be accompanied by tests covering the changed or added functionality. Tests can be run for this library with:

npm install
npm test

When you're ready to push your changes, please run the lint command first:

npm run lint

Support + Feedback

Please use the Issues queue in this repo for questions and feedback.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

What is Auth0?

Auth0 helps you to easily:

• implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
• log in users with username/password databases, passwordless, or multi-factor authentication
• link multiple user accounts together
• generate signed JSON Web Tokens to authorize your API calls and flow the user identity securely
• access demographics and analytics detailing how, when, and where users are logging in
• enrich user profiles from other data sources using customizable JavaScript rules

Why Auth0?

License

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

Changelog

v0.6.0 (2020-01-14)

Full Changelog

Breaking changes in this release:

This release includes important changes to user session and token handling which will require an update for all applications.

First, a new, required configuration key - appSessionSecret (changed to appSession.secret in v0.8.0) - has been added. The value here will be used to generate keys which are in turn used to encrypt the user identity returned from the identity provider. This encrypted and signed identity is stored in a cookie and used to populate the req.openid.user property, as before. This key should be set to either a secure, random value to use this built-in session or false to provide your own custom application session handling. A value for this can be generated with openssl like so:

❯ openssl rand -hex 32
f334eb9ee5898101f90047ec46f18c2f4c082f5eeef109920d6b0fc5b79b6f29

As part of these changes, a session middleware is no longer required for this library. One can be added and used for application session and tokens (see above and below, respectively) but initialization will no longer fail if one is not present.

Additionally, tokens returned from the identity provider will no longer be stored in a session middleware automatically. If your application requires access, refresh, or ID tokens to be retrieved and stored (not just the user identity), you will need to provide a method for that storage in version 0.6.0 and beyond. See our examples page for guidance.

Closed issues

• "legacySameSiteCookie" for auth config params is not yet available in the typings file. #44
• Validate configured routes #21

Added

• Add path validation #47 (joshcanhelp)
• Add typescript defs new config #46 (joshcanhelp)
• Add SameSite support #39 (joshcanhelp)
• Add custom callback handling #37 (joshcanhelp)
• Add body parser to login and callback route #33 (davidpatrick)

Changed

• Change session and token handling #42 (joshcanhelp)