README

express-okta-saml

express-okta-saml is node.js library which creates routes for okta-saml authentication. It is very minimal and clean, using passport-saml and passport libraries to handle the process, gives you all access to passport-saml and passport configs/options.

Why another one?

There is a few other, not maintained libraries that provides middleware for OKTA authentication but all of them introduces configuration abstraction without leaving a way to pass configs/options directly for passport and passport-saml libraries. I simply needed full flexibility of passport-saml and passport-saml to be accessible .

How to use it?

Simple app setup example

const http = require('http');
const session = require('express-session');
const oktaAuth = require('okta-auth');
const expressOktaSaml = require('express-okta-saml');

const hour = 3600000;
const app = express();
app.use(cookieParser());
app.use(session({
  secret:  'my-secret',
  cookie: { maxAge:  hour  *  24 },
  resave:  true,
  saveUninitialized:  true,
  name:  'my-app',
}));

app.use(bodyParser.json()); // important to have bodyParser as OKTA will make POST redirect with body data
app.use(bodyParser.urlencoded({ extended:  false }));
app.get('/ping', (req, res) => { // unprotected healthcheck
  res.statusCode  =  200;
  res.send('pong');
});

const expressOktaSamlConfig = require('./oktaConfig.js'); // check bellow for config exmaple and tips
const okta = expressOktaSaml(app, expressOktaSamlConfig); // setups okta routes + passport
app.use('/', okta.secured); // from here all following requests will be checked for auth
app.get('/test', () => { res.send(''); }); // this will be not reachable if user is not logged in via OKTA

const server = http.createServer(app);
server.listen(3000, (err) => {
  if (err) {
    console.log('Failed to start server');
    console.log(err);
  }
  console.log(`Server has started on port: ${server.address().port}`);
});

oktaConfig.js example

const fs = require('fs');
const path = require('path');

const cert = fs.readFileSync(path.join(__dirname, 'okta.pem'), 'utf8');

module.exports = {
  SAML: {
    passportOptions: { // check full list of available options - https://github.com/bergie/passport-saml
      cert,
      issuer:  'http://www.okta.com/id-from-okta-saml-setup', // your okta issuer url (provided by okta duerning SAML setup)
      entryPoint:  'https://...../sso/saml', // entryPoint url (provided by okta duerning SAML setup)
      callbackUrl:  'http://localhost:3000/login', // your callback url 
    },
    propertiesToExtract: ['Email', 'FirstName', 'LastName'], // these properties will be saved on user session by passport access it by req.user
  },

  passport: {
    options: { //options to be passed to passport.authenticate(). check full list of available options - https://github.com/jaredhanson/passport/blob/master/lib/middleware/authenticate.js
      successRedirect:  '/',
      failureRedirect:  '/login',
      failureFlash:  true,
    },
  },

  appRoutes: { // express-okta-saml will create GET/POST routes on these endpoints to handle auth proccess
    loginPath:  '/login', // make sure this is same as path on SAML.passportOptions.callbackUrl and passport.options.failureRedirect
    logoutPath:  '/logout',
    accessDeniedPath:  '/access-denied',
  },
}

Tips on OKTA

SAML.passportOptions.callbackUrl

OKTA after successful auth will redirect user to this url. It is important that callbackUrl is whitelisted in OKTA SAML setup. If passed callbackUrl URL is not whitelisted, OKTA will ignore it and redirect to the whitelisted one. Check image to see how to whitelist multiple domains/urls for okta auth.

privateCert instead of cert

You can pass private certificate to passport-saml.

Remove SAML.passportOptions.cert and add SAML.passportOptions.privateCert.

Credits

Originally Inspired by wojtekk/okta-auth

Usage no npm install needed!