Change session and token handling

API.md

@@ -11,6 +11,7 @@ The `auth()` middleware has a few configuration keys that are required for initi
 - **`baseURL`** - The root URL for the application router. This can be set automatically with a `BASE_URL` variable in your environment.
 - **`clientID`** - The Client ID for your application. This can be set automatically with a `CLIENT_ID`  variable in your environment.
 - **`issuerBaseURL`** - The root URL for the token issuer with no trailing slash. In Auth0, this is your Application's **Domain** prepended with `https://`. This can be set automatically with an `ISSUER_BASE_URL` variable in your environment.
+- **`appSessionSecret`** - The secret used to derive an encryption key for the user identity in a session cookie. Set this to `false` to skip this internal storage and provide your own session mechanism in `getUser`. This can be set automatically with an `APP_SESSION_SECRET` variable in your environment. It must be a string or an array of strings. When array is provided the first member is used for signing and other members can be used for decrypting old cookies, this is to enable appSessionSecret rotation.
 
 If you are using a response type that includes `code` (typically combined with an `audience` parameter), you will need an additional key:
 
@@ -27,12 +28,16 @@ Additional configuration keys that can be passed to `auth()` on initialization:
 - **`errorOnRequiredAuth`** - Boolean value to throw a `Unauthorized 401` error instead of triggering the login process for routes that require authentication. Default is `false`.
 - **`httpOptions`** - Default options object used for all HTTP calls made by the library ([possible options](https://github.com/sindresorhus/got/tree/v9.6.0#options)). Default is empty.
 - **`idpLogout`** - Boolean value to log the user out from the identity provider on application logout. Requires the issuer to provide a `end_session_endpoint` value. Default is `false`.
+- **`identityClaimFilter`** - Array value of claims to remove from the ID token before storing the cookie session. Default is `['aud', 'iss', 'iat', 'exp', 'nonce', 'azp', 'auth_time']`.
 - **`legacySameSiteCookie`** - Set a fallback cookie with no SameSite attribute when `authorizationParams.response_mode` is `form_post`. Default is `true`.
 - **`loginPath`** - Relative path to application login. Default is `/login`.
 - **`logoutPath`** - Relative path to application logout. Default is `/logout`.
 - **`redirectUriPath`** - Relative path to the application callback to process the response from the authorization server. This value is combined with the `baseUrl` and sent to the authorize endpoint as the `redirectUri` parameter. Default is `/callback`.
 - **`required`** - Use a boolean value to require authentication for all routes. Pass a function instead to base this value on the request. Default is `true`.
 - **`routes`** - Boolean value to automatically install the login and logout routes. See [the examples](EXAMPLES.md) for more information on how this key is used. Default is `true`.
+- **`appSessionDuration`** - Integer value, in seconds, indicating application session length. Set to `0` to indicate the cookie should be ephemeral (no expiration). Default is 7 days.
+- **`appSessionName`** - String value for the cookie name used for the internal session. This value must only include letters, numbers, and underscores. Default is `identity`.
+- **`appSessionCookie`** - Object defining application session cookie attributes. Allowed keys are `domain`, `httpOnly`, `path`, `secure`, and `sameSite`. Defaults are `true` for `httpOnly` and `Lax` for `sameSite`.
 
 ### Authorization Params Key
 
@@ -100,12 +105,12 @@ This library adds properties and methods to the request and response objects use
 
 ### Request
 
-Every request object (typically named `req` in your route handler) is augmented with the following when the request is authenticated. If the request is not authenticated, `req.openid` is `undefined`.
+Every request object (typically named `req` in your route handler) is augmented with the following when the request is authenticated. If the request is not authenticated, `req.openid` is `undefined` and `req.isAuthenticated()` returns `false`.
 
-- **`req.openid.user`** - Contains the user information returned from the authorization server. You can change what is provided here by using the `getUser` configuration key.
-- **`req.openid.tokens`** - Is the [TokenSet](https://github.com/panva/node-openid-client/blob/master/docs/README.md#tokenset) instance obtained during login.
+- **`req.openid.user`** - Contains the user information returned from the authorization server. You can change what is provided here by passing a function to the `getUser` configuration key.
 - **`req.openid.client`** - Is the [OpenID Client](https://github.com/panva/node-openid-client/blob/master/docs/README.md#client) instance that can be used for additional OAuth2 and OpenID calls. See [the examples](EXAMPLES.md) for more information on how this is used.
 - **`req.isAuthenticated()`** - Returns true if the request is authenticated.
+- **`req.makeTokenSet()`** - Make a TokenSet object from a JSON representation of one.
 
 ### Response
 

EXAMPLES.md

@@ -1,7 +1,7 @@
 
 # Examples
 
-## 1. Basic Setup
+## 1. Basic setup
 
 The simplest use case for this middleware:
 
@@ -10,21 +10,12 @@ The simplest use case for this middleware:
 ISSUER_BASE_URL=https://YOUR_DOMAIN
 CLIENT_ID=YOUR_CLIENT_ID
 BASE_URL=https://YOUR_APPLICATION_ROOT_URL
-SESSION_NAME=YOUR_SESSION_NAME
-COOKIE_SECRET=LONG_RANDOM_VALUE
+APP_SESSION_SECRET=LONG_RANDOM_STRING
 ```
 
 ```javascript
 // app.js
 const { auth } = require('express-openid-connect');
-const session = require('cookie-session');
-
-app.use(express.urlencoded({ extended: false }));
-
-app.use(session({
-  name: process.env.SESSION_NAME,
-  secret: process.env.COOKIE_SECRET
-}));
 
 app.use(auth({
   required: true
@@ -65,7 +56,6 @@ Another way to configure this scenario:
 ```js
 const { auth } = require('express-openid-connect');
 
-//initialization
 app.use(auth({
   required: req => req.originalUrl.startsWith('/admin/')
 }));
@@ -75,9 +65,9 @@ app.use('/admin/users', (req, res) => res.render('admin-users'));
 app.use('/admin/posts', (req, res) => res.render('admin-posts'));
 ```
 
-## 3. Route Customization
+## 3. Route customization
 
-If you need to customize the routes, you can opt-out from the default routes and write your own route handler:
+If you need to customize the provided routes, you can opt-out from the default routes and write your own route handler:
 
 ```js
 app.use(auth({ routes: false }));
@@ -98,17 +88,94 @@ app.use(auth({
 
 Please note that both of these routes are completely optional and not required. Trying to access any protected resource triggers a redirect directly to Auth0 to login.
 
-## 4. Using refresh tokens
+## 4. Custom user session handling
+
+By default, this library uses an encrypted cookie to store the user identity claims used as a session. If the size of the user identity is too large or you're concerned about sensitive data being stored, you can provide your own session handling as part of the `getUser` function.
+
+If, for example, you want the user session to be stored on the server, you can use a session middleware like `express-session`. We recommend persisting the data in a session store other than in-memory (which is the default), otherwise all sessions will be lost when the server restarts. The basics of handling the user identity server-side is below:
+
+```js
+const session = require('express-session');
+app.use(session({
+  secret: 'replace this with a long, random, static string',
+  cookie: {
+    // Sets the session cookie to expire after 7 days.
+    maxAge: 7 * 24 * 60 * 60 * 1000
+  }
+}));
+
+app.use(auth({
+  // Setting this configuration key to false will turn off internal session handling.
+  appSessionSecret: false,
+  handleCallback: async function (req, res, next) {
+    // This will store the user identity claims in the session
+    req.session.userIdentity = req.openIdTokens.claims();
+    next();
+  },
+  getUser: async function (req) {
+    return req.session.userIdentity;
+  }
+}));
+```
+
+## 5. Obtaining and storing access tokens to call external APIs
+
+If your application needs to request and store [access tokens](https://auth0.com/docs/tokens/access-tokens) for external APIs, you must provide a method to store the incoming tokens during callback. We recommend to use a persistant store, like a database or Redis, to store these tokens directly associated with the user for which they were requested.
 
-Refresh tokens can be requested along with access tokens using the `offline_access` scope during login:
+If the tokens only need to be used during the user's session, they can be stored using a session middleware like `express-session`. We recommend persisting the data in a session store other than in-memory (which is the default), otherwise all tokens will be lost when the server restarts. The basics of handling the tokens is below:
+
+```js
+const session = require('express-session');
+app.use(session({
+  secret: 'replace this with a long, random, static string',
+  cookie: {
+    // Sets the session cookie to expire after 7 days.
+    maxAge: 7 * 24 * 60 * 60 * 1000
+  }
+}));
+
+app.use(auth({
+  authorizationParams: {
+    response_type: 'code',
+    audience: process.env.API_URL,
+    scope: 'openid profile email read:reports'
+  },
+  handleCallback: async function (req, res, next) {
+    req.session.openIdTokens = req.openIdTokens;
+    next();
+  }
+}));
+```
+
+On a route that needs to use the access token, pull the token data from the storage and initialize a new `TokenSet` using `makeTokenSet()` method exposed by this library:
+
+```js
+app.get('/route-that-calls-an-api', async (req, res, next) => {
+
+  const tokenSet = req.openid.makeTokenSet(req.session.openIdTokens);
+  let apiData = {};
+
+  // Check for and use tokenSet.access_token for the API call ...
+});
+```
+
+## 6. Obtaining and using refresh tokens
+
+[Refresh tokens](https://auth0.com/docs/tokens/refresh-token/current) can be requested along with access tokens using the `offline_access` scope during login. Please see the section on access tokens above for information on token storage.
 
 ```js
 app.use(auth({
   authorizationParams: {
     response_type: 'code id_token',
     response_mode: 'form_post',
+    // API identifier to indicate which API this application will be calling.
     audience: process.env.API_URL,
+    // Include the required scopes as well as offline_access to generate a refresh token.
     scope: 'openid profile email read:reports offline_access'
+  },
+  handleCallback: async function (req, res, next) {
+    // See the "Using access tokens" section above for token handling.
+    next();
   }
 }));
 ```
@@ -119,56 +186,45 @@ On a route that calls an API, check for an expired token and attempt a refresh:
 app.get('/route-that-calls-an-api', async (req, res, next) => {
 
   let apiData = {};
-  let tokenSet = req.openid.tokens;
 
-  if (tokenSet && tokenSet.expired() && tokenSet.refresh_token) {
+  // How the tokenSet is created will depend on how the tokens are stored.
+  let tokenSet = req.openid.makeTokenSet(req.session.openIdTokens);
+  let refreshToken = tokenSet.refresh_token;
+
+  if (tokenSet && tokenSet.expired() && refreshToken) {
     try {
       tokenSet = await req.openid.client.refresh(tokenSet);
     } catch(err) {
       next(err);
     }
 
-    tokenSet.refresh_token = req.openid.tokens.refresh_token;
-    req.openid.tokens = tokenSet;
-  }
+    // New tokenSet may not include a new refresh token.
+    tokenSet.refresh_token = tokenSet.refresh_token ?? refreshToken;
 
-  try {
-    apiData = await request(
-      process.env.API_URL,
-      {
-        headers: { authorization: `Bearer ${tokenSet.access_token}` },
-        json: true
-      }
-    );
-  } catch(err) {
-    next(err);
+    // Where you store the refreshed tokenSet will depend on how the tokens are stored.
+    req.session.openIdTokens = tokenSet;
   }
 
-  res.render('api-data-template', {
-    user: req.openid && req.openid.user,
-    apiData
-  });
+  // Check for and use tokenSet.access_token for the API call ...
 });
 ```
 
-## 5. Calling userinfo
+## 7. Calling userinfo
 
-If your application needs to call the userinfo endpoint for the user's identity, add a `handleCallback` function during initialization that will make this call. To map the incoming claims to the user identity, also add a `getUser` function.
+If your application needs to call the userinfo endpoint for the user's identity instead of the ID token used by default, add a `handleCallback` function during initialization that will make this call. Save the claims retrieved from the userinfo endpoint to the `appSessionName` on the request object (default is `identity`):
 
 ```js
 app.use(auth({
   handleCallback: async function (req, res, next) {
     const client = req.openid.client;
+    req.identity = req.identity || {};
     try {
-      req.session.userinfo = await client.userinfo(req.session.openidTokens);
+      req.identity.claims = await client.userinfo(req.openidTokens);
       next();
     } catch(e) {
       next(e);
     }
   },
-  getUser: function(tokenSet) {
-    return tokenSet && ( tokenSet.userinfo || tokenSet.claims() );
-  },
   authorizationParams: {
     response_type: 'code',
     scope: 'openid profile email'

README.md

@@ -55,22 +55,25 @@ These can be configured in a `.env` file in the root of your application:
 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:
 
 ```js
 // index.js
 
+const { auth } = require('express-openid-connect');
 app.use(auth({
   required: true,
   issuerBaseURL: 'https://YOUR_DOMAIN',
   baseURL: 'https://YOUR_APPLICATION_ROOT_URL',
-  clientID: 'YOUR_CLIENT_ID'
+  clientID: 'YOUR_CLIENT_ID',
+  appSessionKey: 'LONG_RANDOM_STRING'
 }));
 ```
 
-See [Examples](EXAMPLES.md) for how to get started authenticating users.
+See the [Examples](EXAMPLES.md) for how to get started authenticating users.
 
 ## Contributing
 

lib/appSession.js

@@ -0,0 +1,88 @@
+const { strict: assert } = require('assert');
+
+const { JWK, JWKS, JWE } = require('jose');
+const onHeaders = require('on-headers');
+const cookie = require('cookie');
+const hkdf = require('futoin-hkdf');
+
+const deriveKey = (secret) => hkdf(secret, 32, { info: 'JWE CEK', hash: 'SHA-256' });
+const epoch = () => Date.now() / 1000 | 0;
+
+module.exports = ({ name, secret, duration, cookieOptions = {} }) => {
+  let current;
+
+  const COOKIES = Symbol('cookies');
+  const alg = 'dir';
+  const enc = 'A256GCM';
+
+  let keystore = new JWKS.KeyStore();
+
+  if (!Array.isArray(secret)) {
+    secret = [secret];
+  }
+
+  secret.forEach((secretString, i) => {
+    const key = JWK.asKey(deriveKey(secretString));
+    if (i === 0) {
+      current = key;
+    }
+    keystore.add(key);
+  });
+
+  if (keystore.size === 1) {
+    keystore = current;
+  }
+
+  function encrypt (payload, headers) {
+    return JWE.encrypt(payload, current, { alg, enc, zip: 'DEF', ...headers });
+  }
+
+  function decrypt (jwe) {
+    return JWE.decrypt(jwe, keystore, { complete: true, algorithms: [enc] });
+  }
+
+  function setCookie (req, res, { uat = epoch(), iat = uat, exp = uat + duration }) {
+    if ((!req[name] || !Object.keys(req[name]).length) && name in req[COOKIES]) {
+      res.clearCookie(name);
+      return;
+    }
+
+    if (req[name] && Object.keys(req[name]).length > 0) {
+      const value = encrypt(JSON.stringify(req[name]), { iat, uat, exp });
+      const expires = !duration ? 0 : new Date(exp * 1000);
+
+      res.cookie(name, value, {expires, ...cookieOptions});
+    }
+  }
+
+  return (req, res, next) => {
+    if (!req.hasOwnProperty(COOKIES)) {
+      req[COOKIES] = cookie.parse(req.get('cookie') || '');
+    }
+
+    if (req.hasOwnProperty(name)) {
+      return next();
+    }
+
+    let iat;
+    let exp;
+
+    try {
+
+      if (req[COOKIES].hasOwnProperty(name)) {
+        const { protected: header, cleartext } = decrypt(req[COOKIES][name]);
+        ({ iat, exp } = header);
+        assert(exp > epoch());
+        req[name] = JSON.parse(cleartext);
+      }
+    } finally {
+      if (!req.hasOwnProperty(name) || !req[name]) {
+        req[name] = {};
+      }
+    }
+
+    onHeaders(res, setCookie.bind(undefined, req, res, { iat }));
+
+    return next();
+  };
+};