@okta/oidc-middleware

Okta NodeJS OIDC Middleware

• Release status
• Need help?
• Getting started
• Usage guide
• API reference
• Upgrading
• Contributing

This package makes it easy to get your users logged in with Okta using OpenId Connect (OIDC). It enables your Express application to participate in the authorization code flow by redirecting the user to Okta for authentication and handling the callback from Okta. Once this flow is complete, a local session is created and the user context is saved for the duration of the session.

Release status

This library uses semantic versioning and follows Okta's library version policy.

:heavy_check_mark: The current stable major version series is: 2.x

Version	Status
2.x	:heavy_check_mark: Stable
1.x	:x: Deprecated
0.x	:x: Retired

The latest release can always be found on the [releases page][github-releases].

Need help?

If you run into problems using the SDK, you can:

• Ask questions on the Okta Developer Forums
• Post [issues][github-issues] here on GitHub (for code errors)

Getting started

See Upgrading for information on updating to the latest version of the library.

Installing the Okta Node JS OIDC Middlware in your project is simple.

npm install --save @okta/oidc-middleware

You'll also need:

• An Okta account, called an organization (sign up for a free developer organization if you need one).
• An OIDC application in your Org, configured for Web mode. If you are new to Okta or this flow, we suggest following the Express.js Quickstart.
• This integration depends on sessions to store user information. Ensure the express-session middleware is added before you add ExpressOIDC. By default, the session middleware uses a MemoryStore, which is not designed for production use. Use another session store for production.

Usage guide

Below is a terse Express application that examples the basic usage of this library. If you'd like to clone a complete example, please see the Okta Express Samples Repository.

const express = require('express');
const session = require('express-session');
const { ExpressOIDC } = require('@okta/oidc-middleware');

const app = express();
const oidc = new ExpressOIDC({
  issuer: 'https://{yourOktaDomain}/oauth2/default',
  client_id: '{clientId}',
  client_secret: '{clientSecret}',
  appBaseUrl: '{appBaseUrl}',
  scope: 'openid profile'
});

app.use(session({
  secret: 'this-should-be-very-random',
  resave: true,
  saveUninitialized: false
}));
app.use(oidc.router);

app.get('/', (req, res) => {
  if (req.userContext) {
    res.send(`
      Hello ${req.userContext.userinfo.name}!
      <form method="POST" action="/logout">
        <button type="submit">Logout</button>
      </form>
    `);
  } else {
    res.send('Please <a href="/login">login</a>');
  }
});

app.get('/protected', oidc.ensureAuthenticated(), (req, res) => {
  res.send('Top Secret');
});

oidc.on('ready', () => {
  app.listen(3000, () => console.log('app started'));
});

oidc.on('error', err => {
  // An error occurred while setting up OIDC, during token revokation, or during post-logout handling
});

API reference

• Okta NodeJS OIDC Middleware
  • Release status
  • Need help?
  • Getting started
  • Usage guide
  • API reference
    • ExpressOIDC API
      • new ExpressOIDC(config)
      • oidc.router
      • oidc.on('ready', callback)
      • oidc.on('error', callback)
      • oidc.ensureAuthenticated({ redirectTo?: '/uri' })
      • oidc.forceLogoutAndRevoke()
      • req.isAuthenticated()
      • req.logout()
      • req.userContext
    • Customization
      • Customizing Routes
      • Using a Custom Login Page
      • Extending the User
      • Using Proxy Servers
    • Upgrading
      • from 1.x to 2.x
      • from 2.x to 3.x
        • Straightforward Okta logout for your app
        • Local logout
      • Okta with additional apps
  • Contributing
    • Installing dependencies for contributions

ExpressOIDC API

new ExpressOIDC(config)

To configure your OIDC integration, create an instance of ExpressOIDC and pass options. Most apps will need this basic configuration:

const { ExpressOIDC } = require('@okta/oidc-middleware');

const oidc = new ExpressOIDC({
  issuer: 'https://{yourOktaDomain}/oauth2/default',
  client_id: '{clientId}',
  client_secret: '{clientSecret}',
  appBaseUrl: 'https://{yourdomain}',
  scope: 'openid profile'
});

Required config:

• issuer - The OIDC provider (e.g. https://{yourOktaDomain}/oauth2/default)
• client_id - An id provided when you create an OIDC app in your Okta Org
• client_secret - A secret provided when you create an OIDC app in your Okta Org
• appBaseUrl - The base scheme, host, and port (if not 80/443) of your app, not including any path (e.g. http://localhost:8080, not http://localhost:8080/ )

Optional config:

• loginRedirectUri - The URI for your app that Okta will redirect users to after sign in to create the local session. Locally, this is usually http://localhost:8080/authorization-code/callback. When deployed, this should be https://{yourProductionDomain}/authorization-code/callback. if loginRedirectUri is not provided, the value will be set to {appBaseUrl}{routes.loginCallback.path}. Unless your redirect is to a different application, it is recommended to NOT set this parameter and instead set routes.loginCallback.path (if different than the default of /authorization-code/callback) so that the callback will be handled by this module. After the callback has been handled, this module will redirect to the route defined by routes.loginCallback.afterCallback (defaults to /). Your application should handle this route.
• logoutRedirectUri - The URI for your app that Okta will redirect users to after sign out. Defaults to {appBaseUrl}/. Locally this is usually http://localhost:8080/. When deployed, this should be https://{yourProductionDomain}/. Unless your redirect is to a different application, it is recommended to NOT set this parameter and instead set routes.logoutCallback.path (if different than the default of /) so that the callback will map to a route handled by your application.
• response_type - Defaults to code
• scope - Defaults to openid, which will only return the sub claim. To obtain more information about the user, use openid profile. For a list of scopes and claims, please see Scope-dependent claims for more information.
• routes - Allows customization of the generated routes. See Customizing Routes for details.
• maxClockSkew - Defaults to 120. This is the maximum difference allowed between your server's clock and Okta's in seconds. Setting this to 0 is not recommended, because it increases the likelihood that valid jwts will fail verification due to nbf and exp issues.
• timeout - Defaults to 10000 milliseconds. The HTTP max timeout for any requests to the issuer. If a timeout exception occurs you can catch it with the oidc.on('error', fn) handler.

oidc.router

This should be added to your express app to attach the login and callback routes:

const { ExpressOIDC } = require('@okta/oidc-middleware');
const express = require('express');

const app = express();
const oidc = new ExpressOIDC({ /* options */ });

app.use(oidc.router);

The router is required in order for ensureAuthenticated, and isAuthenticated, and forceLogoutAndRevoke to work and adds the following routes:

• /login - redirects to the Okta sign-in page by default
• /authorization-code/callback - processes the OIDC response, then attaches userinfo to the session
• /logout - revokes any known Okta access/refresh tokens, then redirects to the Okta logout endpoint which then redirects back to a callback url for logout specified in your Okta settings

The paths for these generated routes can be customized using the routes config, see Customizing Routes for details.

oidc.on('ready', callback)

The middleware must retrieve some information about your client before starting the server. You must wait until ExpressOIDC is ready to start your server.

oidc.on('ready', () => {
  app.listen(3000, () => console.log('app started'));
});

oidc.on('error', callback)

This is triggered if an error occurs

• while ExpressOIDC is trying to start
• if an error occurs while calling the Okta /revoke service endpoint on the users tokens while logging out
• if the state value for a logout does not match the current session

oidc.on('error', err => {
  // An error occurred
});

oidc.ensureAuthenticated({ redirectTo?: '/uri', loginHint?: 'username' })

Use this to protect your routes. If not authenticated, this will redirect to the login route and trigger the authentication flow. If the request prefers JSON then a 401 error response will be sent.

app.get('/protected', oidc.ensureAuthenticated(), (req, res) => {
  res.send('Protected stuff');
});

The redirectTo option can be used to redirect the user to a specific URI on your site after a successful authentication callback.

Passing loginHint option will append login_hint query parameter to URL when redirecting to Okta-hosted sign in page.

oidc.forceLogoutAndRevoke()

Use this to define a route that will force a logout of the user from Okta and the local session. Because logout involves redirecting to Okta and then to the logout callback URI, the body of this route will never directly execute. It is recommended to not perform logout on GET queries as it is prone to attacks and/or prefetching misadventures.

app.post('/forces-logout', oidc.forceLogoutAndRevoke(), (req, res) => {
  // Nothing here will execute, after the redirects the user will end up wherever the `routes.logoutCallback.path` specifies (default `/`)
});

req.isAuthenticated()

This allows you to determine if a user is authenticated.

app.get('/', (req, res) => {
  if (req.isAuthenticated()) {
    res.send('Logged in');
  } else {
    res.send('Not logged in');
  }
});

req.logout()

This allows you to end the local session while leaving the user logged in to Okta, meaning that if they attempt to reauthenticate to your app they will not be prompted to re-enter their credentials unless their Okta session has expired. To end the Okta session, POST to the autogenerated /logout route or send the user to a route you defined using the oidc.forceLogoutAndRevoke() method above.

app.get('/local-logout', (req, res) => {
  req.logout();
  res.redirect('/');
});

req.userContext

This provides information about the authenticated user and contains the requested tokens. The userContext object contains two keys:

1. userinfo: The response from the userinfo endpoint of the authorization server.
2. tokens: TokenSet object containing the accessToken, idToken, and/or refreshToken requested from the authorization server.

Note: Claims reflected in the userinfo response and token object depend on the scope requested (see scope option above).

app.get('/', (req, res) => {
  if (req.userContext) {
    const tokenSet = req.userContext.tokens;
    const userinfo = req.userContext.userinfo;

    console.log(`Access Token: ${tokenSet.access_token}`);
    console.log(`Id Token: ${tokenSet.id_token}`);
    console.log(`Claims: ${tokenSet.claims}`);
    console.log(`Userinfo Response: ${userinfo}`);

    res.send(`Hi ${userinfo.sub}!`);
  } else {
    res.send('Hi!');
  }
});

Customization

Customizing Routes

If you need to modify the default login and callback routes, the routes config option is available.

const oidc = new ExpressOIDC({
  // ...
  routes: {
    login: {
      // handled by this module
      path: '/different/login'
    },
    loginCallback: {
      // handled by this module
      path: '/different/callback',
      handler: (req, res, next) => {
        // Perform custom logic before final redirect, then call next()
      },
      // handled by your application
      afterCallback: '/home'
    },
    logout: {
      // handled by this module
      path: '/different/logout'
    },
    logoutCallback: {
      // handled by your application
      path: '/different/logout-callback'
    }
  }
});

• loginCallback.afterCallback - Where the user is redirected to after a successful authentication callback, if no redirectTo value was specified by oidc.ensureAuthenticated(). Defaults to /.
• loginCallback.failureRedirect - Where the user is redirected to after authentication failure. Defaults to a page which just shows error message.
• loginCallback.handler - A function that is called after a successful authentication callback, but before the final redirect within your application. Useful for requirements such as conditional post-authentication redirects, or sending data to logging systems.
• loginCallback.path - The URI that this library will host the login callback handler on. Defaults to /authorization-code/callback. Must match a value from the Login Redirect Uri list from the Okta console for this application.
• login.path - The URI that redirects the user to the Okta authorize endpoint. Defaults to /login.
• logout.path - The URI that redirects the user to the Okta logout endpoint. Defaults to /logout.
• logoutCallback.path - Where the user is redirected to after a successful logout callback, if no redirectTo value was specified by oidc.forceLogoutAndRevoke(). Defaults to /. Must match a value from the Logout Redirect Uri list from the Okta console for this application.

Using a Custom Login Page

By default the end-user will be redirected to the Okta Sign-In Page when authentication is required, this page is hosted on your Okta Org domain. It is possible to host this experience within your own application by installing the Okta Sign-In Widget into a page in your application. Please refer to the test example file for an example of how the widget should be configured for this use case.

Once you have created your login page, you can use the viewHandler option to intercept the login page request and render your own custom page:

const oidc = new ExpressOIDC({
  { /* options */ }
  routes: {
    login: {
      viewHandler: (req, res, next) => {
        const baseUrl = url.parse(baseConfig.issuer).protocol + '//' + url.parse(baseConfig.issuer).host;
        // Render your custom login page, you must create this view for your application and use the Okta Sign-In Widget
        res.render('login', {
          csrfToken: req.csrfToken(),
          baseUrl: baseUrl
        });
      }
    }
  }
});

Extending the User

To add additional data about a user from your database, we recommend adding middleware to extend req.

const { ExpressOIDC } = require('@okta/oidc-middleware');
const express = require('express');
const session = require('express-session');

const app = express();
app.use(session({ /* options */ }));
const oidc = new ExpressOIDC({ /* options */ });
app.use(oidc.router);

function addUserContext(req, res, next) {
  if (!req.userContext) {
    return next();
  }

  // request additional info from your database
  User.findOne({ id: req.userContext.userinfo.sub }, (err, user) => {
    if (err) return next(err);
    req.user = user;
    next();
  });
}

app.use(addUserContext);

{ /* options */ } // add other routes

oidc.on('ready', () => app.listen(3000));
oidc.on('error', err => console.log('could not start', err));

Using Proxy Servers

warning: Due to the deprecation of the request library and the drop of support from openid-client library. The using proxy servers feature is currently broken.

The underlying [openid-client][https://github.com/panva/node-openid-client] library can be configured to use the [request][https://github.com/request/request] library. Do this by adding these lines to your app, before you call new ExpressOIDC():

const Issuer = require('openid-client').Issuer;

Issuer.useRequest();

const oidc = new ExpressOIDC({
  ...
});

Once you have done that you can read the documentation on the request library to learn which environment variables can be used to define your proxy settings.

Upgrading

from 1.x to 2.x

The 2.x improves support for default options without removing flexibility and adds logout functionality that includes Okta logout and token revocation, not just local session destruction.

Specify the appBaseUrl property in your config - this is the base scheme + domain + port for your application that will be used for generating the URIs validated against the Okta settings for your application.

Remove the redirect_uri property in your config.

• If you are using the Okta default value (appBaseUrl + /authorization-code/callback) it will be given a route by default, no additional configuration required.
• If you are NOT using the Okta default value, but are using a route on the same server indicated by your appBaseUrl, you should define your login callback path in your routes.loginCallback.path config (see the API reference).

Any customization previously done to routes.callback should now be done to routes.loginCallback as the name of that property object has changed.

Any value previously set for routes.callback.defaultRedirect should now be done to routes.loginCallback.afterCallback.

from 2.x to 3.x

This library no longer provides a handler for the logout callback, which was by default /logout/callback. The default logout callback is now {appBaseUrl}/, but it can be set to any URI or route handled by your application. The URI must be added to the Logout Redirect Uri list for this application from the Okta Admin console. If your app is currently configured to use /logout/callback, you can either change the callback URI from the Okta console or add a handler for the /logout/callback route. If your app is setting a value for routes.logoutCallback.afterCallback you should move this value to routes.logoutCallback.path. routes.logoutCallback.afterCallback has been deprecated and is no longer used.

Straightforward Okta logout for your app

Configure a logout redirect uri for your application in the Okta admin console for your application, if one is not already defined

• If you do not, logouts will not return to your application but will end on the Okta site
• Okta recommends {appBaseUrl}/. Be sure to fully specify the uri for your application
• If you chose a different logout redirect uri, specify the path for the local route to create in your routes.logoutCallback.path value (see the API reference).

By default the middleware will create a /logout (POST only) route. You should remove any local /logout route you have added - if it only destroyed the local session (per the example from the 1.x version of this library) you can simply remove it. If it did additional post-logout logic, you can change the path of the route and list that path in the route.logoutCallback.afterCallback option (see the API reference).

Local logout

If you had previously implemented a '/logout' route that called req.logout() (performing a local logout for your app) you should remove that route and use the new automatically added /logout route. If you used that route using direct links or GET requests, those will have to become POST requests. You can create a GET route for /logout, but that as a GET request is open for abuse and/or pre-fetching complications it is not recommended.

If you desire to have a route that performs a local logout while leaving the user logged in to Okta, you can create any route you wish (that does not conflict with automatically created routes) and call req.logout() to destroy your local session without altering the status of the user's browser session at Okta.

Okta with additional apps

If you had the redirect_uri pointing to a different application than this one, replace redirect_uri with loginRedirectUri, and consider if you need to set logoutRedirectUri.

Contributing

We welcome contributions to all of our open-source packages. Please see the contribution guide to understand how to structure a contribution.

Installing dependencies for contributions

We use yarn for dependency management when developing this package:

yarn install