soajs.controller 4.3.14 → 4.3.16

package/docs/configuration-custom-registry.md

@@ -27,6 +27,9 @@ registry.custom
 │       │       └── [service]       # Service-specific settings
 │       ├── maintenanceMode         # Gateway maintenance mode
 │       ├── lastSeen                # User activity tracking
+│       ├── membership              # Membership on the urac object, by product
+│       │   ├── active              # Whether membership is resolved at all
+│       │   └── [main product]      # Its sub products
 │       ├── oauth
 │       │   └── deviceIdCheck       # Turn the deviceId check off
 │       └── gotoService
@@ -494,6 +497,86 @@ is read by the oauth middleware itself.
 
 ---
 
+## 14. Membership
+
+**Path:** `registry.custom.gateway.value.membership`
+
+**Middleware:** `mw/mt/index.js`, resolved by `lib/membership.js`
+
+Puts the caller's membership on the urac object of every call, so a service can read it
+without a lookup.
+
+A membership is held per main product on the user record in the urac `users` collection,
+and only its name is stored. What the name grants is resolved from the catalog, it is
+never copied onto the user:
+
+```javascript
+{
+  "memberships": [
+    { "product": "AVAPP", "membership": "whale" }
+  ]
+}
+```
+
+The gateway already resolves both halves of the match on every call. The access token
+gives the user record, which carries `memberships`, and the API key gives the product the
+call is made under. Resolution is the match between them: if the product of the request
+is a configured main product or one of its sub products, and the user holds an entry for
+that main product, the membership name is injected.
+
+```javascript
+{
+  "membership": {
+    "active": true,                          // Resolve membership at all
+    "AVAPP": ["CLUBS", "CORPS", "SECRT", "GRPCH"]   // Main product and its sub products
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `active` | boolean | `false` | Whether the gateway resolves membership at all |
+| `[main product]` | string[] | - | A product a membership is held in, valued by the sub products that resolve to it |
+
+Every key other than `active` is read as a main product, so more than one can be
+configured and they stay independent. A main product always resolves to itself, listing
+sub products is optional.
+
+### What the service sees
+
+```javascript
+req.soajs.urac.membership     // "whale"
+```
+
+Only the resolved name travels. The raw `memberships` array is never injected, so a
+service cannot read a membership held for a product the request was not made under.
+
+### It fails closed
+
+Nothing is injected, and no service sees a membership, when any of these hold:
+
+| | |
+|---|---|
+| the block is absent, or `active` is not `true` | membership is off |
+| no main product is configured | nothing is resolvable, equivalent to off |
+| the request product is neither a main product nor a sub product | out of scope |
+| the user holds no entry for the resolved main product | no membership |
+| the service does not request urac (`urac: false`) | there is no urac object to put it on |
+
+Product codes are matched exactly. They are uppercase by convention, and normalizing
+here would hide a miscased entry in the registry rather than surface it.
+
+### Freshness
+
+The user record behind this comes from the access token when
+`serviceConfig.oauth.getUserFromToken` is on, when the login mode is `oauth`, or when
+roaming. In those cases `memberships` is a snapshot taken at login, and a membership
+changed afterwards is not seen until a new token is issued. Refreshing does not help,
+the refresh grant copies the stored user forward unchanged. Otherwise the record is
+loaded from urac per request and the membership is current.
+
+---
+
 ## Complete Configuration Example
 
 ```javascript
@@ -615,6 +698,7 @@ Custom registry configurations are processed in this order:
 | 5 | gotoService/redirectToService | `gotoService.monitor` |
 | 6 | mt (security checks) | `mt.whitelist`, `oauth.value.pinWrapper`, `oauth.value.pinWhitelist` |
 | 6a | oauth (called from mt) | `oauth.deviceIdCheck` |
+| 6b | mt (inject object) | `membership` |
 | 7 | idempotency | `idempotency.model`, `idempotency.services.[name]` |
 | 8 | traffic | `traffic.model`, `traffic.throttling` |
 | 9 | cache | `cache.model`, `cache.defaultTTL`, `cache.services.[name]` |

package/docs/middleware/mt.md

@@ -515,6 +515,7 @@ The `soajsinjectobj` header contains:
     "lastName": "Doe",
     "email": "user@example.com",
     "groups": ["group1"],
+    "membership": "whale",     // If resolved, see custom registry `membership`
     "tenant": { "id": "...", "code": "..." },
     "profile": { ... },        // If urac_Profile enabled
     "acl": { ... },            // If urac_ACL enabled

package/docs/middleware/oauth.md

@@ -70,6 +70,13 @@ Uses oauth2-server library for token validation.
            ├─── Mismatch ──▶ Error 156
            │
            ▼
+  ┌─────────────────────────┐
+  │  restrictedTo check     │ token user.restrictedTo vs the request
+  └────────┬────────────────┘
+           │
+           ├─── Mismatch ──▶ Error 147
+           │
+           ▼
        next()
 ```
 
@@ -107,6 +114,53 @@ Read from `registry.custom.gateway.value.oauth.deviceIdCheck`. Only the boolean
 turns it off, any other value leaves it on, so a missing or malformed entry keeps the
 check running.
 
+#### restrictedTo check
+
+A minted token can carry a `restrictedTo` object under `user`, scoping it to where it may be
+used. It is checked on the record `authorise()` already fetched, so it costs no extra database
+call.
+
+```json
+{
+  "restrictedTo": {
+    "tenant": "<tenant id>",
+    "product": "PRODWEB"
+  }
+}
+```
+
+Only the keys present are checked. **A token with no `restrictedTo` is not checked at all**,
+so every token issued before restricted tokens existed behaves exactly as before. Each key
+takes a string or an array of strings.
+
+There is no registry switch for this check, unlike `deviceIdCheck` above. Writing a
+restriction onto a token is the opt in, and once it is there it is always enforced.
+
+| key | compared against |
+|-----|------------------|
+| `tenant` | `req.soajs.tenant.id` |
+| `product` | `req.soajs.tenant.application.product` |
+| `package` | `req.soajs.tenant.application.package` |
+| `key` | `req.soajs.tenant.key.eKey` |
+| `env` | the gateway environment, matched case insensitively |
+| `agent` | the `user-agent` request header |
+
+The first five come from the ext key on the request, which `mw/mt` resolves before oauth runs.
+So a token minted for one tenant and product is refused on any other key, which is the point.
+
+`agent` is an exact match, and this is the only place agent is ever enforced. The login and
+refresh flows do not check it, so setting it affects nothing but the token that carries it.
+Use it only on short lived tokens, a user-agent string changes whenever the browser updates.
+
+This check is only available for type 2, a type 0 JWT carries no stored token record.
+
+##### Failing closed
+
+A service with `extKeyRequired` off gives the request no key, so there is nothing to compare
+against. A token carrying `restrictedTo` is **denied** in that case rather than allowed
+through, otherwise a restricted token could escape its restriction by targeting a keyless
+service.
+
 ### Type 0: JWT
 
 Uses jsonwebtoken library for JWT validation.
@@ -199,6 +253,7 @@ Default OAuth service configuration:
 | Code | Description |
 |------|-------------|
 | 143 | Invalid or missing JWT token |
+| 147 | Token restriction mismatch, the token's restrictedTo does not allow this request |
 | 156 | Device forbidden, the deviceId on the token does not match the device-id header |
 | OAuth2Error | Various OAuth2 errors (invalid_token, expired, etc.) |
 

package/lib/membership.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * @license
+ * Copyright SOAJS All Rights Reserved.
+ *
+ * Use of this source code is governed by an Apache license that can be
+ * found in the LICENSE file at the root of this repository
+ */
+
+/**
+ * Resolve the membership the caller holds for the product this request is made under.
+ *
+ * A membership is held per main product on the user record, and only its name is
+ * stored. What the name grants is resolved from the catalog, it is never copied
+ * onto the user:
+ *
+ *   "memberships": [{ "product": "AVAPP", "membership": "whale" }]
+ *
+ * A request carries the product of the key it was made with. That product is either
+ * the main product itself or one of its sub products, and both resolve to the main
+ * product, so a call made under CLUBS reads the AVAPP membership.
+ *
+ * Configured at registry.custom.gateway.value.membership, keyed by main product:
+ *
+ *   {
+ *     "active": true,
+ *     "AVAPP": ["CLUBS", "CORPS", "SECRT", "GRPCH"]
+ *   }
+ *
+ * NOTE: this fails closed. An absent or inactive block, an unconfigured product, or
+ *       a user with no entry for the resolved main product all resolve to null, and
+ *       nothing is injected, so no service sees a membership it should not.
+ *
+ * @param config the custom registry membership block
+ * @param product the product the request is made under, ex: keyObj.application.product
+ * @param memberships the memberships array off the user record
+ * @returns {string|null} the membership name, or null when it does not resolve
+ */
+function resolveMembership(config, product, memberships) {
+	if (!config || !config.active) {
+		return null;
+	}
+	if (!product || !Array.isArray(memberships) || memberships.length === 0) {
+		return null;
+	}
+
+	//NOTE: product codes are matched exactly, they are uppercase by convention and
+	//      normalizing here would hide a miscased entry in the registry
+	let mainProduct = null;
+	let configuredProducts = Object.keys(config).filter((key) => {
+		return key !== "active";
+	});
+	for (let i = 0; i < configuredProducts.length; i++) {
+		let key = configuredProducts[i];
+		if (key === product || (Array.isArray(config[key]) && config[key].includes(product))) {
+			mainProduct = key;
+			break;
+		}
+	}
+	if (!mainProduct) {
+		return null;
+	}
+
+	for (let i = 0; i < memberships.length; i++) {
+		let entry = memberships[i];
+		if (entry && entry.product === mainProduct && entry.membership) {
+			return entry.membership;
+		}
+	}
+	return null;
+}
+
+module.exports = { resolveMembership };

package/mw/mt/index.js

@@ -14,6 +14,9 @@ const utils = require("./utils");
 
 
 const { encodeHeaderValue } = require("../../lib/header.js");
+const { resolveMembership } = require("../../lib/membership.js");
+
+const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
 
 /**
  *
@@ -266,6 +269,15 @@ module.exports = (configuration) => {
 													}
 												};
 
+												//NOTE: only the resolved name travels, never the raw per product
+												//		array, so a service cannot read a membership held for
+												//		a product this request was not made under
+												let membershipConfig = get(["soajs", "registry", "custom", "gateway", "value", "membership"], req);
+												let membership = resolveMembership(membershipConfig, keyObj.application.product, uracObj.memberships);
+												if (membership) {
+													injectObj.urac.membership = membership;
+												}
+
 												injectObj.param = injectObj.param || {};
 												injectObj.param.urac_Profile = serviceParam.urac_Profile;
 												injectObj.param.urac_ACL = serviceParam.urac_ACL;

package/mw/mt/urac.js

@@ -167,6 +167,13 @@ Urac.prototype.getProfile = function (_ALL) {
 			"tenant": _self.userRecord.tenant
 		};
 
+		//NOTE: the raw per product array. The gateway resolves the one entry that applies
+		//		to this request and injects only that, see lib/membership.js. Set only when
+		//		the record carries it, so a user with no memberships keeps the shape it had.
+		if (_self.userRecord.memberships) {
+			urac.memberships = _self.userRecord.memberships;
+		}
+
 		if (_self.userRecord.socialLogin) {
 			urac.socialLogin = {
 				"strategy": _self.userRecord.socialLogin.strategy,

package/mw/oauth/index.js

@@ -13,6 +13,10 @@
  * @param configuration
  * @returns {Function}
  */
+//NOTE: the token env is stamped the same way at soajs.core/provision/mongo.js, so the
+//		restrictedTo env constraint is compared against the identical expression.
+let regEnvironment = (process.env.SOAJS_ENV || "dev").toLowerCase();
+
 module.exports = (configuration) => {
 	
 	configuration.soajs.oauthService = configuration.soajs.param.oauthService || {};
@@ -81,6 +85,77 @@ module.exports = (configuration) => {
 		return req.oauth.bearerToken.user.deviceId === req.get('device-id');
 	};
 
+	/**
+	 * Matches one constraint, a string or an array of strings, against the request value.
+	 *
+	 * @param allowed {String|Array} what the token allows
+	 * @param actual {String} what the request carries
+	 * @param ignoreCase {Boolean} used for env, where the registry casing is not guaranteed
+	 * @returns {boolean} true when the request value is allowed
+	 */
+	let valueMatch = (allowed, actual, ignoreCase) => {
+		if (!actual) {
+			return false;
+		}
+		if (ignoreCase) {
+			let lower = actual.toLowerCase();
+			if (Array.isArray(allowed)) {
+				return allowed.some((one) => {
+					return one && one.toLowerCase() === lower;
+				});
+			}
+			return !!allowed && allowed.toLowerCase() === lower;
+		}
+		if (Array.isArray(allowed)) {
+			return allowed.includes(actual);
+		}
+		return allowed === actual;
+	};
+
+	/**
+	 * Enforces the restrictedTo object carried on the access token record.
+	 *
+	 * NOTE: only the keys present on restrictedTo are checked, a token with no restrictedTo is
+	 *		not checked at all. that is the opt in, there is no registry switch, a restriction
+	 *		written on a token is always enforced.
+	 *
+	 * NOTE: it fails closed. a restricted token reaching a service with extKeyRequired off has
+	 *		no key to be compared against, it must not gain access that way.
+	 *
+	 * @param req
+	 * @returns {boolean} true when the request is allowed to proceed
+	 */
+	let restrictedToMatch = (req) => {
+		if (!req.oauth || !req.oauth.bearerToken || !req.oauth.bearerToken.user || !req.oauth.bearerToken.user.restrictedTo) {
+			return true;
+		}
+		let restrictedTo = req.oauth.bearerToken.user.restrictedTo;
+
+		if (!req.soajs.tenant || !req.soajs.tenant.application) {
+			req.soajs.log.debug("Access denied, restricted token on a request with no key");
+			return false;
+		}
+
+		let actual = {
+			"tenant": req.soajs.tenant.id,
+			"product": req.soajs.tenant.application.product,
+			"package": req.soajs.tenant.application.package,
+			"key": req.soajs.tenant.key ? req.soajs.tenant.key.eKey : null,
+			"env": regEnvironment,
+			"agent": req.get('user-agent')
+		};
+
+		for (let field in actual) {
+			if (Object.hasOwnProperty.call(actual, field) && restrictedTo[field]) {
+				if (!valueMatch(restrictedTo[field], actual[field], "env" === field)) {
+					req.soajs.log.debug("Access denied, token restriction mismatch on [" + field + "]");
+					return false;
+				}
+			}
+		}
+		return true;
+	};
+
 	return (req, res, next) => {
 
 		let oauthType = 2;
@@ -103,6 +178,9 @@ module.exports = (configuration) => {
 					req.soajs.log.debug("Access denied, deviceId mismatch [deviceId: " + req.get('device-id') + "]");
 					return next(156);
 				}
+				if (!restrictedToMatch(req)) {
+					return next(147);
+				}
 				return next();
 			});
 		} else {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soajs.controller",
   "description": "soajs multi tenant API gateway",
-  "version": "4.3.14",
+  "version": "4.3.16",
   "author": {
     "name": "soajs team",
     "email": "team@soajs.org"
@@ -23,14 +23,14 @@
     "http-proxy": "1.18.1",
     "jsonwebtoken": "9.0.3",
     "kubernetes-client": "9.0.0",
-    "lodash": "4.17.23",
+    "lodash": "4.18.1",
     "merge": "2.1.1",
-    "netmask": "2.0.2",
+    "netmask": "2.1.1",
     "oauth2-server": "2.4.1",
-    "path-to-regexp": "8.4.0",
+    "path-to-regexp": "8.4.2",
     "soajs.core.libs": "1.2.2",
-    "soajs.core.modules": "5.2.20",
-    "soajs.urac.driver": "3.2.16",
+    "soajs.core.modules": "5.2.21",
+    "soajs.urac.driver": "3.2.17",
     "useragent": "2.3.0"
   },
   "devDependencies": {

package/test/unit/index.js

@@ -11,6 +11,7 @@ describe("Starting Gateway Unit test", () => {
         require("./lib/http.js");
         require("./lib/ip.js");
         require("./lib/logOnce.js");
+        require("./lib/membership.js");
         require("./lib/param.js");
         require("./lib/parseURL.js");
 

package/test/unit/lib/membership.js

@@ -0,0 +1,146 @@
+"use strict";
+
+/**
+ * @license
+ * Copyright SOAJS All Rights Reserved.
+ *
+ * Use of this source code is governed by an Apache license that can be
+ * found in the LICENSE file at the root of this repository
+ */
+
+const assert = require('assert');
+const helper = require("../../helper.js");
+
+const { resolveMembership } = helper.requireModule('./lib/membership.js');
+
+describe("Unit test for: lib - membership", () => {
+
+	const CONFIG = {
+		"active": true,
+		"AVAPP": ["CLUBS", "CORPS", "SECRT", "GRPCH"]
+	};
+	const MEMBERSHIPS = [{ "product": "AVAPP", "membership": "whale" }];
+
+	describe("resolving", () => {
+
+		it("resolves when the request is made under the main product", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", MEMBERSHIPS), "whale");
+			done();
+		});
+
+		it("resolves when the request is made under a sub product", (done) => {
+			["CLUBS", "CORPS", "SECRT", "GRPCH"].forEach((sub) => {
+				assert.strictEqual(resolveMembership(CONFIG, sub, MEMBERSHIPS), "whale", "failed for " + sub);
+			});
+			done();
+		});
+
+		it("resolves the main product itself when it has no sub products", (done) => {
+			assert.strictEqual(resolveMembership({ "active": true, "AVAPP": [] }, "AVAPP", MEMBERSHIPS), "whale");
+			done();
+		});
+
+		it("picks the entry for the resolved main product, not the first one", (done) => {
+			let memberships = [
+				{ "product": "OTHER", "membership": "minnow" },
+				{ "product": "AVAPP", "membership": "whale" }
+			];
+			assert.strictEqual(resolveMembership(CONFIG, "CLUBS", memberships), "whale");
+			done();
+		});
+
+		it("keeps several main products independent", (done) => {
+			let config = {
+				"active": true,
+				"AVAPP": ["CLUBS"],
+				"BVAPP": ["BOATS"]
+			};
+			let memberships = [
+				{ "product": "AVAPP", "membership": "whale" },
+				{ "product": "BVAPP", "membership": "dolphin" }
+			];
+			assert.strictEqual(resolveMembership(config, "CLUBS", memberships), "whale");
+			assert.strictEqual(resolveMembership(config, "BOATS", memberships), "dolphin");
+			done();
+		});
+	});
+
+	describe("failing closed", () => {
+
+		it("resolves nothing when the block is absent", (done) => {
+			assert.strictEqual(resolveMembership(null, "AVAPP", MEMBERSHIPS), null);
+			assert.strictEqual(resolveMembership(undefined, "AVAPP", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing when active is not set", (done) => {
+			assert.strictEqual(resolveMembership({ "AVAPP": ["CLUBS"] }, "AVAPP", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing when active is false", (done) => {
+			assert.strictEqual(resolveMembership({ "active": false, "AVAPP": ["CLUBS"] }, "CLUBS", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing when no product is configured", (done) => {
+			assert.strictEqual(resolveMembership({ "active": true }, "AVAPP", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing for a product that is neither main nor sub", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, "UNRELATED", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing when the user holds no entry for the main product", (done) => {
+			let memberships = [{ "product": "OTHER", "membership": "minnow" }];
+			assert.strictEqual(resolveMembership(CONFIG, "CLUBS", memberships), null);
+			done();
+		});
+
+		it("resolves nothing when the user has no memberships", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", null), null);
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", []), null);
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", undefined), null);
+			done();
+		});
+
+		it("resolves nothing when the request carries no product", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, null, MEMBERSHIPS), null);
+			done();
+		});
+
+		it("matches product codes exactly, a miscased code does not resolve", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, "clubs", MEMBERSHIPS), null);
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", [{ "product": "avapp", "membership": "whale" }]), null);
+			done();
+		});
+	});
+
+	describe("malformed input", () => {
+
+		it("survives a memberships array holding junk", (done) => {
+			let memberships = [null, "whale", { "product": "AVAPP" }, { "membership": "whale" }];
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", memberships), null);
+			done();
+		});
+
+		it("skips an entry with no membership name and keeps looking", (done) => {
+			let memberships = [{ "product": "AVAPP" }, { "product": "AVAPP", "membership": "whale" }];
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", memberships), "whale");
+			done();
+		});
+
+		it("survives a sub product list that is not an array", (done) => {
+			assert.strictEqual(resolveMembership({ "active": true, "AVAPP": "CLUBS" }, "CLUBS", MEMBERSHIPS), null);
+			assert.strictEqual(resolveMembership({ "active": true, "AVAPP": "CLUBS" }, "AVAPP", MEMBERSHIPS), "whale");
+			done();
+		});
+
+		it("does not treat active as a product", (done) => {
+			assert.strictEqual(resolveMembership({ "active": true }, "active", [{ "product": "active", "membership": "x" }]), null);
+			done();
+		});
+	});
+});

package/test/unit/mw/oauth/index.js

@@ -267,3 +267,228 @@ describe("Unit test for: mw - oauth deviceId check", () => {
         });
     });
 });
+
+describe("Unit test for: mw - oauth restrictedTo check", () => {
+
+    // builds a configuration whose model returns an access token carrying the given restrictedTo
+    let buildConfiguration = (restrictedTo) => {
+        let user = {"id": "1"};
+        if (restrictedTo !== undefined) {
+            user.restrictedTo = restrictedTo;
+        }
+        return {
+            "soajs": {
+                "param": {}
+            },
+            "serviceConfig": {
+                "oauth": {
+                    grants: ["password", "refresh_token"],
+                    debug: false,
+                    accessTokenLifetime: 7200,
+                    refreshTokenLifetime: 1209600
+                }
+            },
+            "model": {
+                "getAccessToken": (bearerToken, cb) => {
+                    return cb(null, {
+                        "token": bearerToken,
+                        "expires": new Date(new Date().getTime() + 3600000),
+                        "user": user
+                    });
+                }
+            }
+        };
+    };
+
+    // oauthType 2 so that the access token is fetched from the model
+    // tenant mirrors what mw/mt sets from the ext key before oauth runs
+    let buildReq = (agent) => {
+        return {
+            "soajs": {
+                "log": {
+                    "debug": () => {
+                    }
+                },
+                "tenant": {
+                    "id": "tenantB",
+                    "key": {
+                        "eKey": "theWebAppExtKey"
+                    },
+                    "application": {
+                        "product": "PRODWEB",
+                        "package": "PRODWEB_BASIC"
+                    }
+                },
+                "tenantOauth": {
+                    "type": 2
+                },
+                "servicesConfig": {},
+                "registry": {
+                    "serviceConfig": {
+                        "oauth": {
+                            "type": 2
+                        }
+                    }
+                }
+            },
+            "query": {},
+            "body": {},
+            "get": (what) => {
+                if ('Authorization' === what) {
+                    return "Bearer anAccessToken";
+                }
+                if ('user-agent' === what) {
+                    return agent;
+                }
+                return undefined;
+            }
+        };
+    };
+    let res = {};
+
+    it("test oauth MW - no restrictedTo, token is not checked", (done) => {
+        let functionMw = mw(buildConfiguration(undefined));
+        functionMw(buildReq(), res, (error) => {
+            assert.ifError(error);
+            done();
+        });
+    });
+
+    it("test oauth MW - tenant and product match", (done) => {
+        let functionMw = mw(buildConfiguration({"tenant": "tenantB", "product": "PRODWEB"}));
+        functionMw(buildReq(), res, (error) => {
+            assert.ifError(error);
+            done();
+        });
+    });
+
+    it("test oauth MW - tenant does not match", (done) => {
+        let functionMw = mw(buildConfiguration({"tenant": "tenantA"}));
+        functionMw(buildReq(), res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - product does not match", (done) => {
+        let functionMw = mw(buildConfiguration({"product": "PRODMOBILE"}));
+        functionMw(buildReq(), res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - package and ext key match", (done) => {
+        let functionMw = mw(buildConfiguration({"package": "PRODWEB_BASIC", "key": "theWebAppExtKey"}));
+        functionMw(buildReq(), res, (error) => {
+            assert.ifError(error);
+            done();
+        });
+    });
+
+    it("test oauth MW - ext key does not match", (done) => {
+        let functionMw = mw(buildConfiguration({"key": "someOtherExtKey"}));
+        functionMw(buildReq(), res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - array of allowed products, one matches", (done) => {
+        let functionMw = mw(buildConfiguration({"product": ["PRODMOBILE", "PRODWEB"]}));
+        functionMw(buildReq(), res, (error) => {
+            assert.ifError(error);
+            done();
+        });
+    });
+
+    it("test oauth MW - array of allowed products, none matches", (done) => {
+        let functionMw = mw(buildConfiguration({"product": ["PRODMOBILE", "PRODOTHER"]}));
+        functionMw(buildReq(), res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - several constraints, the last one fails", (done) => {
+        let functionMw = mw(buildConfiguration({
+            "tenant": "tenantB",
+            "product": "PRODWEB",
+            "key": "someOtherExtKey"
+        }));
+        functionMw(buildReq(), res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - env matches whatever the gateway runs as, case insensitive", (done) => {
+        let current = (process.env.SOAJS_ENV || "dev").toLowerCase();
+        let functionMw = mw(buildConfiguration({"env": current.toUpperCase()}));
+        functionMw(buildReq(), res, (error) => {
+            assert.ifError(error);
+            done();
+        });
+    });
+
+    it("test oauth MW - env does not match", (done) => {
+        let functionMw = mw(buildConfiguration({"env": "anEnvThatIsNotRunning"}));
+        functionMw(buildReq(), res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - agent matches", (done) => {
+        let functionMw = mw(buildConfiguration({"agent": "Mozilla/5.0 theBrowser"}));
+        functionMw(buildReq("Mozilla/5.0 theBrowser"), res, (error) => {
+            assert.ifError(error);
+            done();
+        });
+    });
+
+    it("test oauth MW - agent does not match", (done) => {
+        let functionMw = mw(buildConfiguration({"agent": "Mozilla/5.0 theBrowser"}));
+        functionMw(buildReq("Mozilla/5.0 anotherBrowser"), res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - agent constrained but request sends none, denied", (done) => {
+        let functionMw = mw(buildConfiguration({"agent": "Mozilla/5.0 theBrowser"}));
+        functionMw(buildReq(undefined), res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - fails closed when the request carries no key", (done) => {
+        let functionMw = mw(buildConfiguration({"product": "PRODWEB"}));
+        let req = buildReq();
+        delete req.soajs.tenant;
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+
+    it("test oauth MW - a restriction on the token cannot be switched off at the registry", (done) => {
+        let functionMw = mw(buildConfiguration({"tenant": "tenantA"}));
+        let req = buildReq();
+        req.soajs.registry.custom = {
+            "gateway": {
+                "value": {
+                    "oauth": {
+                        "restrictedToCheck": false,
+                        "deviceIdCheck": false
+                    }
+                }
+            }
+        };
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 147);
+            done();
+        });
+    });
+});