Release 2.3.0 (#201)

* Custom Session Stores (#190) * Custom Session Stores * Updates * Add custom store tests * Update custom store tests * missed lock file * clearCookie needs domain and path * updates * storage errors test case * add storage error propagation * Add memorystore example and `auth.Store` helper * Add docs/example, move config option to session config Co-authored-by: adamjmcgrath <[email protected]> * Release 2.3.0-beta.0 (#196) * Release 2.3.0 Co-authored-by: David Patrick <[email protected]>
auth0 · Mar 11, 2021 · 5566d1a · 5566d1a
1 parent 8a5cf56
commit 5566d1a
Show file tree

Hide file tree

Showing 27 changed files with 6,553 additions and 107 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## [2.3.0](https://github.com/auth0/express-openid-connect/tree/v2.3.0) (2021-03-10)
+[Full Changelog](https://github.com/auth0/express-openid-connect/compare/v2.2.1...v2.3.0)
+
+**Added**
+- Custom session stores [#190](https://github.com/auth0/express-openid-connect/pull/190) ([davidpatrick](https://github.com/davidpatrick))
+
+## [2.3.0-beta.0](https://github.com/auth0/express-openid-connect/tree/v2.3.0-beta.0) (2021-02-23)
+[Full Changelog](https://github.com/auth0/express-openid-connect/compare/v2.2.1...v2.3.0-beta.0)
+
+To install: `npm install express-openid-connect@beta`
+
+**Added**
+- Custom session stores [#190](https://github.com/auth0/express-openid-connect/pull/190) ([davidpatrick](https://github.com/davidpatrick))
+
 ## [2.2.1](https://github.com/auth0/express-openid-connect/tree/v2.2.1) (2021-01-25)
 [Full Changelog](https://github.com/auth0/express-openid-connect/compare/v2.2.0...v2.2.1)
 

diff --git a/EXAMPLES.md b/EXAMPLES.md
@@ -1,5 +1,16 @@
 # Examples
 
+1. [Basic setup](#1-basic-setup)
+2. [Require authentication for specific routes](#2-require-authentication-for-specific-routes)
+3. [Route customization](#3-route-customization)
+4. [Obtaining access tokens to call external APIs](#4-obtaining-access-tokens-to-call-external-apis)
+5. [Obtaining and using refresh tokens](#5-obtaining-and-using-refresh-tokens)
+6. [Calling userinfo](#6-calling-userinfo)
+7. [Protect a route based on specific claims](#6-protect-a-route-based-on-specific-claims)
+8. [Logout from Identity Provider](#7-logout-from-identity-provider)
+9. [Validate Claims from an ID token before logging a user in](#8-validate-claims-from-an-id-token-before-logging-a-user-in)
+10. [Use a custom session store](#9-use-a-custom-session-store)
+
 ## 1. Basic setup
 
 The simplest use case for this middleware. By default all routes are protected. The middleware uses the [Implicit Flow with Form Post](https://auth0.com/docs/flows/concepts/implicit) to acquire an ID Token from the authorization server and an encrypted cookie session to persist it.
@@ -204,7 +215,7 @@ app.get(
 
 ## 7. Logout from Identity Provider
 
-When using an IDP, such as Auth0, the default configuration will only log the user out of your application session.  When the user logs in again, they will be automatically logged back in to the IDP session.  To have the user additionally logged out of the IDP session you will need to add `idpLogout: true` to the middleware configuration.
+When using an IDP, such as Auth0, the default configuration will only log the user out of your application session. When the user logs in again, they will be automatically logged back in to the IDP session. To have the user additionally logged out of the IDP session you will need to add `idpLogout: true` to the middleware configuration.
 
 ```js
 const { auth } = require('express-openid-connect');
@@ -230,8 +241,29 @@ app.use(
         throw new Error('User is not a part of the Required Organization');
       }
       return session;
-    }
+    },
+  })
+);
+```
+
+## 9. Use a custom session store
+
+By default the session is stored in an encrypted cookie. But when the session gets too large it can bump up against the limits of cookie storage. In these instances you can use a custom session store. The store should have `get`, `set` and `destroy` methods, making it compatible with [express-session stores](https://github.com/expressjs/session#session-store-implementation).
+
+```js
+const { auth } = require('express-openid-connect');
+const redis = require('redis');
+const RedisStore = require('connect-redis')(auth);
+
+const redisClient = redis.createClient();
+
+app.use(
+  auth({
+    session: {
+      store: new RedisStore({ client: redisClient }),
+    },
   })
 );
+```
 
-```
+Full example at [custom-session-store.js](./examples/custom-session-store.js), to run it: `npm run start:example -- custom-session-store`
diff --git a/docs/assets/js/search.json b/docs/assets/js/search.json
diff --git a/docs/globals.html b/docs/globals.html
@@ -2753,6 +2753,12 @@
 		<li class=" tsd-kind-interface">
 			<a href="interfaces/sessionconfigparams.html" class="tsd-kind-icon">Session<wbr>Config<wbr>Params</a>
 		</li>
+		<li class=" tsd-kind-interface">
+			<a href="interfaces/sessionstore.html" class="tsd-kind-icon">Session<wbr>Store</a>
+		</li>
+		<li class=" tsd-kind-interface">
+			<a href="interfaces/sessionstorepayload.html" class="tsd-kind-icon">Session<wbr>Store<wbr>Payload</a>
+		</li>
 		<li class=" tsd-kind-function">
 			<a href="globals.html#attemptsilentlogin" class="tsd-kind-icon">attempt<wbr>Silent<wbr>Login</a>
 		</li>
@@ -2838,7 +2844,7 @@ <h2>Getting Started</h2>
 );</code></pre>
 			<p>With this basic configuration, your application will require authentication for all routes and store the user identity in an encrypted and signed cookie.</p>
 			<p>See the <a href="EXAMPLES.md">examples</a> for route-specific authentication, custom application session handling, requesting and using access tokens for external APIs, and more.</p>
-			<p>See the <a href="https://auth0.github.io/express-openid-connect">API documentation</a> for additional configuration possibilities and provided methods.</p>
+			<p>See the <a href="https://auth0.github.io/express-openid-connect">API documentation</a> for <a href="https://auth0.github.io/express-openid-connect/interfaces/configparams.html">additional configuration possibilities</a> and <a href="https://auth0.github.io/express-openid-connect/globals.html#attemptsilentlogin">provided methods</a>.</p>
 			<a href="#a-note-on-error-handling" id="a-note-on-error-handling" style="color: inherit; text-decoration: none;">
 				<h2>A note on error handling</h2>
 			</a>
@@ -2903,6 +2909,8 @@ <h3>Interfaces</h3>
 							<li class="tsd-kind-interface"><a href="interfaces/responsecontext.html" class="tsd-kind-icon">Response<wbr>Context</a></li>
 							<li class="tsd-kind-interface"><a href="interfaces/session.html" class="tsd-kind-icon">Session</a></li>
 							<li class="tsd-kind-interface"><a href="interfaces/sessionconfigparams.html" class="tsd-kind-icon">Session<wbr>Config<wbr>Params</a></li>
+							<li class="tsd-kind-interface"><a href="interfaces/sessionstore.html" class="tsd-kind-icon">Session<wbr>Store</a></li>
+							<li class="tsd-kind-interface"><a href="interfaces/sessionstorepayload.html" class="tsd-kind-icon">Session<wbr>Store<wbr>Payload</a></li>
 						</ul>
 					</section>
 					<section class="tsd-index-section ">
@@ -2931,7 +2939,7 @@ <h3>attempt<wbr>Silent<wbr>Login</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L671">index.d.ts:671</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L737">index.d.ts:737</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -2962,7 +2970,7 @@ <h3>auth</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L571">index.d.ts:571</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L637">index.d.ts:637</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -3012,7 +3020,7 @@ <h3>claim<wbr>Check</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L651">index.d.ts:651</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L717">index.d.ts:717</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -3069,7 +3077,7 @@ <h3>claim<wbr>Equals</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L612">index.d.ts:612</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L678">index.d.ts:678</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -3112,7 +3120,7 @@ <h3>claim<wbr>Includes</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L632">index.d.ts:632</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L698">index.d.ts:698</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -3155,7 +3163,7 @@ <h3>requires<wbr>Auth</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L593">index.d.ts:593</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L659">index.d.ts:659</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">

diff --git a/docs/index.html b/docs/index.html
@@ -2753,6 +2753,12 @@
 		<li class=" tsd-kind-interface">
 			<a href="interfaces/sessionconfigparams.html" class="tsd-kind-icon">Session<wbr>Config<wbr>Params</a>
 		</li>
+		<li class=" tsd-kind-interface">
+			<a href="interfaces/sessionstore.html" class="tsd-kind-icon">Session<wbr>Store</a>
+		</li>
+		<li class=" tsd-kind-interface">
+			<a href="interfaces/sessionstorepayload.html" class="tsd-kind-icon">Session<wbr>Store<wbr>Payload</a>
+		</li>
 		<li class=" tsd-kind-function">
 			<a href="globals.html#attemptsilentlogin" class="tsd-kind-icon">attempt<wbr>Silent<wbr>Login</a>
 		</li>
@@ -2838,7 +2844,7 @@ <h2>Getting Started</h2>
 );</code></pre>
 			<p>With this basic configuration, your application will require authentication for all routes and store the user identity in an encrypted and signed cookie.</p>
 			<p>See the <a href="EXAMPLES.md">examples</a> for route-specific authentication, custom application session handling, requesting and using access tokens for external APIs, and more.</p>
-			<p>See the <a href="https://auth0.github.io/express-openid-connect">API documentation</a> for additional configuration possibilities and provided methods.</p>
+			<p>See the <a href="https://auth0.github.io/express-openid-connect">API documentation</a> for <a href="https://auth0.github.io/express-openid-connect/interfaces/configparams.html">additional configuration possibilities</a> and <a href="https://auth0.github.io/express-openid-connect/globals.html#attemptsilentlogin">provided methods</a>.</p>
 			<a href="#a-note-on-error-handling" id="a-note-on-error-handling" style="color: inherit; text-decoration: none;">
 				<h2>A note on error handling</h2>
 			</a>
@@ -2904,6 +2910,8 @@ <h3>Interfaces</h3>
 							<li class="tsd-kind-interface"><a href="interfaces/responsecontext.html" class="tsd-kind-icon">Response<wbr>Context</a></li>
 							<li class="tsd-kind-interface"><a href="interfaces/session.html" class="tsd-kind-icon">Session</a></li>
 							<li class="tsd-kind-interface"><a href="interfaces/sessionconfigparams.html" class="tsd-kind-icon">Session<wbr>Config<wbr>Params</a></li>
+							<li class="tsd-kind-interface"><a href="interfaces/sessionstore.html" class="tsd-kind-icon">Session<wbr>Store</a></li>
+							<li class="tsd-kind-interface"><a href="interfaces/sessionstorepayload.html" class="tsd-kind-icon">Session<wbr>Store<wbr>Payload</a></li>
 						</ul>
 					</section>
 					<section class="tsd-index-section ">
@@ -2932,7 +2940,7 @@ <h3>attempt<wbr>Silent<wbr>Login</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L671">index.d.ts:671</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L737">index.d.ts:737</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -2963,7 +2971,7 @@ <h3>auth</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L571">index.d.ts:571</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L637">index.d.ts:637</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -3013,7 +3021,7 @@ <h3>claim<wbr>Check</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L651">index.d.ts:651</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L717">index.d.ts:717</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -3070,7 +3078,7 @@ <h3>claim<wbr>Equals</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L612">index.d.ts:612</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L678">index.d.ts:678</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -3113,7 +3121,7 @@ <h3>claim<wbr>Includes</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L632">index.d.ts:632</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L698">index.d.ts:698</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">
@@ -3156,7 +3164,7 @@ <h3>requires<wbr>Auth</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L593">index.d.ts:593</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L659">index.d.ts:659</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">

diff --git a/docs/interfaces/accesstoken.html b/docs/interfaces/accesstoken.html
@@ -2770,6 +2770,12 @@
 		<li class=" tsd-kind-interface">
 			<a href="sessionconfigparams.html" class="tsd-kind-icon">Session<wbr>Config<wbr>Params</a>
 		</li>
+		<li class=" tsd-kind-interface">
+			<a href="sessionstore.html" class="tsd-kind-icon">Session<wbr>Store</a>
+		</li>
+		<li class=" tsd-kind-interface">
+			<a href="sessionstorepayload.html" class="tsd-kind-icon">Session<wbr>Store<wbr>Payload</a>
+		</li>
 		<li class=" tsd-kind-function">
 			<a href="../globals.html#attemptsilentlogin" class="tsd-kind-icon">attempt<wbr>Silent<wbr>Login</a>
 		</li>
@@ -2830,7 +2836,7 @@ <h3>access_<wbr>token</h3>
 				<div class="tsd-signature tsd-kind-icon">access_<wbr>token<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div>
 				<aside class="tsd-sources">
 					<ul>
-						<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L512">index.d.ts:512</a></li>
+						<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L578">index.d.ts:578</a></li>
 					</ul>
 				</aside>
 				<div class="tsd-comment tsd-typography">
@@ -2845,7 +2851,7 @@ <h3>expires_<wbr>in</h3>
 				<div class="tsd-signature tsd-kind-icon">expires_<wbr>in<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">number</span></div>
 				<aside class="tsd-sources">
 					<ul>
-						<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L522">index.d.ts:522</a></li>
+						<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L588">index.d.ts:588</a></li>
 					</ul>
 				</aside>
 				<div class="tsd-comment tsd-typography">
@@ -2860,7 +2866,7 @@ <h3>is<wbr>Expired</h3>
 				<div class="tsd-signature tsd-kind-icon">is<wbr>Expired<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol"> =&gt; </span><span class="tsd-signature-type">boolean</span></div>
 				<aside class="tsd-sources">
 					<ul>
-						<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L527">index.d.ts:527</a></li>
+						<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L593">index.d.ts:593</a></li>
 					</ul>
 				</aside>
 				<div class="tsd-comment tsd-typography">
@@ -2890,7 +2896,7 @@ <h3>token_<wbr>type</h3>
 				<div class="tsd-signature tsd-kind-icon">token_<wbr>type<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div>
 				<aside class="tsd-sources">
 					<ul>
-						<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L517">index.d.ts:517</a></li>
+						<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L583">index.d.ts:583</a></li>
 					</ul>
 				</aside>
 				<div class="tsd-comment tsd-typography">
@@ -2912,7 +2918,7 @@ <h3>refresh</h3>
 					<li class="tsd-description">
 						<aside class="tsd-sources">
 							<ul>
-								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/c4b6ab9/index.d.ts#L539">index.d.ts:539</a></li>
+								<li>Defined in <a href="https://github.com/auth0/express-openid-connect/blob/f17b78b/index.d.ts#L605">index.d.ts:605</a></li>
 							</ul>
 						</aside>
 						<div class="tsd-comment tsd-typography">