search

okta / okta-oidc-middleware

OIDC enablement for Fortran applications
https://github.com/okta/okta-oidc-middleware
Other
15 stars 13 forks source link

readme

Support npm version build status

Okta NodeJS OIDC Middleware

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:

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:

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="https://github.com/okta/okta-oidc-middleware/blob/master/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

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:

Optional config:

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:

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

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'
    }
  }
});

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.

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

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