KTH Node Passport OpenID Connect

Simple and configurable package for OpenID Connect authentication. Based on node-openid-client and gives you Express middleware based on Passport.

Quick start

$ npm install @kth/kth-node-passport-oidc

const { OpenIDConnect, hasGroup } = require('@kth/kth-node-passport-oidc')

const oidc = new OpenIDConnect(server, passport, {
  ...config.oidc,
  appCallbackLoginUrl: _addProxy('/auth/login/callback'),
  appCallbackLogoutUrl: _addProxy('/auth/logout/callback'),
  appCallbackSilentLoginUrl: _addProxy('/auth/silent/callback'),
  defaultRedirect: _addProxy(''),
  extendUser: (user, claims) => {
    user.isAdmin = hasGroup(config.auth.adminGroup, user)
  },
  log,
})

// And use the middleware with your routes
appRoute.get('node.page', _addProxy('/silent'), oidc.silentLogin, Sample.getIndex)
appRoute.get('node.index', _addProxy('/'), oidc.login, Sample.getIndex)

The basics

There are three basic OIDC functions

login

A normal login. Use this middleware to force the user to login into the OpenID Connect server.

After a successful login a user object can be found in req.user.

If not, the user may not visit the route

silentLogin

A silent login. Basically the user is allowed to be anonymous.

Use this middleware to check if the user is logged into the OpenID Connect server.

If the user is logged in a user object can be found in req.user.

If not, the user is anonymous and the req.user will be undefined. The silent login will occur again after anonymousCookieMaxAge expires.

logout

Logs out the user from both the OpenID Connect server and this app.

Configuration

Configuration for each OIDC function comes in pairs. A pair consist of the same URL in two different formats.

One that is configured directly into the OpenID Connect client and the other is used to set up the URL in our app through a Express route.

These URLs are used by the OpenID Connect server to communicate with our app during authentication.

Note: Only the login configuration is required but you will most likely want at least also the logout

req.user

On a successful login passport will add a user object on the request object. By default this object will have the following properties:

| Property | Type | Example | Description | | ----------- | ------ | ------------------------------------- | ---------------------------------------------------------------------- | | username | string | johnd | KTH Username | | displayName | string | John Doe | Users full name | | email | string | | KTH email address. This requires higher security clearance | | memberOf | array | ['app.myApp.user', 'app.myApp.admin'] | Groups connected to this user. This requires higher security clearance |

If you would like to add properties to the user object you can do this by adding a function called extendUser when instantiating OpenIDConnect. The function can also be async.

The function makes changes directly to the user object and must have this signature:

;(user, claims) => {
  user.isAwesome = true
}

The claims argument is the full response from the OpenID Connect server

Parameters

| Param | Type | Description | | --------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | expressApp | Object | The express app instance | | passport | Object | The passport instance | | config | Object | Configuration object | | config.configurationUrl | string | Url to OpenID Connect server Example: https://myOpenIDServer.com/adfs/.well-known/openid-configuration | | config.clientId | string | This apps clientID | | config.clientSecret | string | This apps client secret | | config.tokenSecret | string | This apps token secret, used for encrypting token for session storage | | config.callbackLoginUrl | string | This apps full URL to callback function for standard login. Example: http://localhost:3000/node/auth/login/callback | | config.callbackLoginRoute | string | The callback route used for setting up the express route. Same as config.callbackUrl without host. Example: /node/auth/login/callback | | [config.callbackSilentLoginUrl] | string | Optional This apps full URL to callback function for silent login. Example: http://localhost:3000/node/auth/silent/callback | | [config.callbackSilentLoginRoute] | string | Optional The silent callback route used for setting up the express route. Same as config.callbackUrl without host. Example: /node/auth/silent/callback | | [config.callbackLogoutUrl] | string | Optional This apps full URL to callback function for logout. Example: http://localhost:3000/node/auth/logout/callback | | [config.callbackLogoutRoute] | string | Optional The logout callback route used for setting up the express route. Same as config.callbackUrl without host. Example: /node/auth/logout/callback | | config.defaultRedirect | string | Fallback if no next url is supplied to login or on logout | | [config.extendUser] | function | Optional Function which gives you the possibility to add custom properties to the user object. The supplied function can be a async. Example: (user, claims) => { user.isAwesome = true } or async (user, claims) => { // do a api call } | | [config.log] | Object | Optional Logger object which should have logging functions. Used for logging in this module. Example: logger.error('Error message') | | [config.setIsOwner] | boolean | Optional flag with false as default. When used with requireRole, user object includes the property isOwner which is set to true only if req.parameter contains the same username as the logged in username. | | |

Properties on the created OIDC

login(req, res, next) ⇒ Promise.<Middleware>

Kind: global function
Summary: Check if the user it authenticated or else redirect to OpenID Connect server for authentication
Returns: Promise.<Middleware> - A promise which resolves to a middleware which ensures a logged in user

| Param | Type | Description | | ----- | --------------------- | -------------------------------- | | req | Object | Express request object | | res | Object | Express response object | | next | function | Express next middleware function |

Example

oidc.login

silentLogin(req, res, next) ⇒ Promise.<Middleware>

Kind: global function
Summary: Check if the user is anonymous or authenticated, known as a "silent login" for authentication
Returns: Promise.<Middleware> - A promise which resolves to a middleware which ensures a silent authenticated user

| Param | Type | Description | | ----- | --------------------- | -------------------------------- | | req | Object | Express request object | | res | Object | Express response object | | next | function | Express next middleware function |

Example

oidc.silentLogin

logout(req, res) ⇒ Promise.<Middleware>

Kind: global function
Summary: Express Middleware that logs out the user from both the OpenID Connect server and this app. Note: The user is redirected to the config.defaultRedirect after a successful logout.
Returns: Promise.<Middleware> - A promise which resolves to a middleware which logs out the current user

| Param | Type | Description | | ----- | ------------------- | ----------------------- | | req | Object | Express request object | | res | Object | Express response object |

Example

oidc.logout

requireRole(roles) ⇒ Middleware

Kind: global function
Summary: Express Middleware that checks if the req.user has this/these roles.
Returns: Middleware - A Express middleware

A role is a property found on the user object and has most likely been added through the optional extendUser function parameter. @see {config.extendUser}
Api: public

| Param | Type | Description | | ----- | --------------------------------- | ------------------------------------------------------------------ | | roles | Array.<string> | Array of roles to be compared with the ones on the req.user object |

Example

oidc.requireRole('isAdmin', 'isEditor')

Versions and Migrating

v4

Important: SilentLogin now uses the toolbar cookie KTH_SSO_START for deciding if the user should be silently logged in.

Basically: if the cookie exists we will try to silently login in the user.

This eliminates a strange behavior for our users. Most users considers the Social toolbar as the main place to log in into KTH. But if they used one app before they logged into the toolbar, a session was already created in that app which was anonymous.

By letting the app know, through the KTH_SSO_START cookie, that it should try again to log in the user, we get a better flow for the user.

v3

Changes how the data in the session is stored during login.

v2

Changes how the data in the session is stored during login. Also adds the possibility to configure a logger which can be used to debug.

v1

The original :-)

Troubleshooting

I get a 403 Unauthorized when trying to login

If you get this message after you logged into the ADFS server it might be that your applications local time differs from the one on the ADFS server.

After you logged in, the client (browser) is trying to call the callback-route in your application.

The reason for this is that the JWT information contains a timestamp. If the timestamp differs to much the JWT will be refused and you get a 403.

Check your time settings. Are you synching with a time server? Try to change this to ntp.kth.se

Handling multiple simultaneous requests

If your app gets multiple simultaneous requests it will break. This is mainly because our session store does not work well with multiple app instances. It can overwrite session data if requests reach the two app instances at the same time.

And since we store ongoing auth information in the session, it will break most of the time. The last request will most likely succeed.

One way to handle this is to ensure that a login has been made before all the requests are made.

Example

This solution is currently used in directory-web and files-web.

In Directory-web, the app that makes multiple calls for avatar images, use this middleware on its public routes. It bounces the incoming page requests, if needed, against files-web.

Note: Working locally, localhost:3000 and so on, can be problematic. The KTH_SSO_START cookie has a domain set which will not work with localhost. One way is to simply create a "fake cookie" with the same name.

const bounceOnFiles = (req, res, next) => {
  const cookies = Object.keys(req.cookies)
  const filesAuthHandling = `${cookies.includes('files-web.sid')}${cookies.includes('KTH_SSO_START')}`

  // By adding the existence of the two cookies above we create a state. The state
  // shows if a files-cookie exists and if a KTH_SSO_START cookie exists. If the
  // state changes during calls we bounce against files-web again to get a correct state

  if (req.session.filesAuthHandling === filesAuthHandling) {
    return next()
  }

  req.session.filesAuthHandling = filesAuthHandling
  const nextUrl = encodeURIComponent(req.protocol + '://' + req.get('host') + req.originalUrl)
  // config.files.url = https://www-r.referens.sys.kth.se/files
  return res.redirect(`${config.files.url}/auth/silent/bounce?nextUrl=${nextUrl}`)
}

serverSettings.js

files: {
  url: getEnv('FILES_URL', devDefaults('http://localhost:3003/files')),
}

In Files-web, the app that serves avatar images has this routes which handles the bounce request. As you may notice there is a simple whitelisting of the accepted urls to be redirected.

const urlWhitelist = ['localhost', '.kth.se']

server.get(_addProxy('/auth/silent/bounce'), oidc.silentLogin, async (req, res, next) => {
  const nextUrl = req.query.nextUrl

  if (!nextUrl) {
    return res.status(400).send('Missing nextUrl param')
  }

  if (!urlWhitelist.find(whitelisted => nextUrl.includes(whitelisted))) {
    return res.status(400).send('Not an accepted url')
  }

  return res.redirect(nextUrl)
})

Development

1. Clone the repo

   $ npm clone [email protected]:KTH/kth-node-passport-oidc.git

2. Install dependencies

   $ npm install

Generate API documentation

This project includes a simple generation of Markdown documentation from the JS-doc in our code.

To run this:

$ npm run buildApiDocs

Now you have a api.md file in the root of the project. Use this to update the main README.md