soajs.controller 4.3.15 → 4.3.16

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/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.15",
+  "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/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();
+        });
+    });
+});