soajs.controller 4.3.7 → 4.3.9

package/docs/configuration-custom-registry.md

@@ -27,6 +27,8 @@ registry.custom
 │       │       └── [service]       # Service-specific settings
 │       ├── maintenanceMode         # Gateway maintenance mode
 │       ├── lastSeen                # User activity tracking
+│       ├── oauth
+│       │   └── deviceIdCheck       # Turn the deviceId check off
 │       └── gotoService
 │           ├── monitor             # Request monitoring config
 │           └── renewReqMonitorOff  # Disable timeout renewal
@@ -448,6 +450,37 @@ Whitelists specific APIs that can be accessed when a user is PIN-locked (during
 
 ---
 
+## 13. OAuth Device ID Check
+
+**Path:** `registry.custom.gateway.value.oauth.deviceIdCheck`
+
+**Middleware:** `mw/oauth/index.js`
+
+Turns off the deviceId check done when authorising an access token. The check matches
+`user.deviceId` on the access token record against the `device-id` header on every
+private API call, and denies with error 156 on mismatch.
+
+```javascript
+{
+  "oauth": {
+    "deviceIdCheck": false                   // Turn off the deviceId check
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `deviceIdCheck` | boolean | `true` | Set to `false` to turn the deviceId check off |
+
+Only the boolean `false` turns the check off. Any other value, and a missing or
+malformed entry, leaves it on.
+
+Note this is a `gateway` entry, not an `oauth` one. The `registry.custom.oauth.value.*`
+entries above are consumed by `mw/mt/utils.js` and `mw/gotoService/roaming.js`, this one
+is read by the oauth middleware itself.
+
+---
+
 ## Complete Configuration Example
 
 ```javascript
@@ -514,6 +547,9 @@ Whitelists specific APIs that can be accessed when a user is PIN-locked (during
       "api": "/user/last/seen",
       "network": "production"
     },
+    "oauth": {
+      "deviceIdCheck": false
+    },
     "gotoService": {
       "monitor": {
         "blacklist": ["soamonitor", "urac"]
@@ -565,6 +601,7 @@ Custom registry configurations are processed in this order:
 | 4 | gotoService/preRedirect | `gotoService.renewReqMonitorOff` |
 | 5 | gotoService/redirectToService | `gotoService.monitor` |
 | 6 | mt (security checks) | `mt.whitelist`, `oauth.value.pinWrapper`, `oauth.value.pinWhitelist` |
+| 6a | oauth (called from mt) | `oauth.deviceIdCheck` |
 | 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/oauth.md

@@ -60,9 +60,53 @@ Uses oauth2-server library for token validation.
   │    bearerToken: user,   │
   │    type: 2              │
   │  }                      │
-  └─────────────────────────┘
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  deviceId check         │ token user.deviceId vs device-id header
+  └────────┬────────────────┘
+           │
+           ├─── Mismatch ──▶ Error 156
+           │
+           ▼
+       next()
 ```
 
+#### deviceId check
+
+The access token record carries `user.deviceId`, set at login from the `device-id`
+header and carried forward across refreshes. It is matched against the `device-id`
+header on every private API call. The check runs on the record `authorise()` already
+fetched, so it costs no extra database call.
+
+The agent cannot be used for this, mobile sends the build number in the user-agent
+(ie: `democav/142 CFNetwork/3826.400.120 Darwin/24.3.0`) which changes on every build.
+
+Tokens with no `deviceId` are not checked. This covers tokens created before deviceId
+was introduced and clients that do not send the header at all, both get checked once
+the client logs in again with the header. A client that sends `device-id` on login but
+omits it on API calls is denied, the header has to be sent consistently.
+
+This check is only available for type 2, a type 0 JWT carries no stored token record.
+
+##### Turning it off
+
+The check is on by default. To turn it off for an environment, set `deviceIdCheck` to
+`false` under the `gateway` custom registry entry:
+
+```json
+{
+  "oauth": {
+    "deviceIdCheck": false
+  }
+}
+```
+
+Read from `registry.custom.gateway.value.oauth.deviceIdCheck`. Only the boolean `false`
+turns it off, any other value leaves it on, so a missing or malformed entry keeps the
+check running.
+
 ### Type 0: JWT
 
 Uses jsonwebtoken library for JWT validation.
@@ -155,6 +199,7 @@ Default OAuth service configuration:
 | Code | Description |
 |------|-------------|
 | 143 | Invalid or missing JWT token |
+| 156 | Device forbidden, the deviceId on the token does not match the device-id header |
 | OAuth2Error | Various OAuth2 errors (invalid_token, expired, etc.) |
 
 ## Properties Set

package/mw/oauth/index.js

@@ -32,9 +32,57 @@ module.exports = (configuration) => {
 	});
 	
 	let jwt = require('jsonwebtoken');
-	
+
+	/**
+	 * The deviceId check is on unless it is explicitly turned off at the custom registry.
+	 * Anything other than false leaves it on.
+	 *
+	 * req.soajs.registry.custom.gateway.value.oauth
+	 * {
+		  "oauth": {
+			"deviceIdCheck": false
+		  }
+		}
+	 *
+	 * @param req
+	 * @returns {boolean} true when the check is turned on
+	 */
+	let deviceIdCheckOn = (req) => {
+		if (req.soajs.registry &&
+			req.soajs.registry.custom &&
+			req.soajs.registry.custom.gateway &&
+			req.soajs.registry.custom.gateway.value &&
+			req.soajs.registry.custom.gateway.value.oauth &&
+			req.soajs.registry.custom.gateway.value.oauth.deviceIdCheck === false) {
+			return false;
+		}
+		return true;
+	};
+
+	/**
+	 * Matches the deviceId on the access token record against the device-id header.
+	 *
+	 * NOTE: we cannot check for agent, mobile is sending the build number
+	 *       (ie: "democav/142 CFNetwork/3826.400.120 Darwin/24.3.0") which changes on every build.
+	 *       we check deviceId instead. tokens with no deviceId (created before deviceId was
+	 *       introduced, or by a client that does not send the header) are not checked, they get
+	 *       checked once the client logs in again.
+	 *
+	 * @param req
+	 * @returns {boolean} true when the request is allowed to proceed
+	 */
+	let deviceIdMatch = (req) => {
+		if (!deviceIdCheckOn(req)) {
+			return true;
+		}
+		if (!req.oauth || !req.oauth.bearerToken || !req.oauth.bearerToken.user || !req.oauth.bearerToken.user.deviceId) {
+			return true;
+		}
+		return req.oauth.bearerToken.user.deviceId === req.get('device-id');
+	};
+
 	return (req, res, next) => {
-		
+
 		let oauthType = 2;
 		let tenantOauth = req.soajs.tenantOauth;
 		if (tenantOauth && Object.hasOwnProperty.call(tenantOauth, 'type')) {
@@ -45,7 +93,18 @@ module.exports = (configuration) => {
 		
 		//0=oauth0, 2=oauth2
 		if (2 === oauthType) {
-			oauthObj.authorise()(req, res, next);
+			//NOTE: authorise() sets req.oauth.bearerToken to the token record it fetched from the
+			//		model, the deviceId check is done on it here to avoid fetching the token again.
+			oauthObj.authorise()(req, res, (error) => {
+				if (error) {
+					return next(error);
+				}
+				if (!deviceIdMatch(req)) {
+					req.soajs.log.debug("Access denied, deviceId mismatch [deviceId: " + req.get('device-id') + "]");
+					return next(156);
+				}
+				return next();
+			});
 		} else {
 			let algorithms = req.soajs.registry.serviceConfig.oauth.algorithms || ["HS256"];
 			let audience = req.soajs.registry.serviceConfig.oauth.audience || "";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soajs.controller",
   "description": "soajs multi tenant API gateway",
-  "version": "4.3.7",
+  "version": "4.3.9",
   "author": {
     "name": "soajs team",
     "email": "team@soajs.org"
@@ -29,7 +29,7 @@
     "oauth2-server": "2.4.1",
     "path-to-regexp": "8.4.0",
     "soajs.core.libs": "1.2.2",
-    "soajs.core.modules": "5.2.19",
+    "soajs.core.modules": "5.2.20",
     "soajs.urac.driver": "3.2.15",
     "useragent": "2.3.0"
   },

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

@@ -99,3 +99,171 @@ describe("Unit test for: mw - oauth", () => {
         });
     });
 });
+
+describe("Unit test for: mw - oauth deviceId check", () => {
+
+    // builds a configuration whose model returns an access token carrying the given deviceId
+    let buildConfiguration = (deviceId) => {
+        let user = {"id": "1"};
+        if (deviceId !== undefined) {
+            user.deviceId = deviceId;
+        }
+        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
+    let buildReq = (headerDeviceId) => {
+        return {
+            "soajs": {
+                "log": {
+                    "debug": () => {
+                    }
+                },
+                "tenantOauth": {
+                    "type": 2
+                },
+                "servicesConfig": {},
+                "registry": {
+                    "serviceConfig": {
+                        "oauth": {
+                            "type": 2
+                        }
+                    }
+                }
+            },
+            "query": {},
+            "body": {},
+            "get": (what) => {
+                if ('Authorization' === what) {
+                    return "Bearer anAccessToken";
+                }
+                if ('device-id' === what) {
+                    return headerDeviceId;
+                }
+                return undefined;
+            }
+        };
+    };
+    let res = {};
+
+    it("test oauth MW - deviceId matches", (done) => {
+        let functionMw = mw(buildConfiguration("2222222222"));
+        let req = buildReq("2222222222");
+        functionMw(req, res, (error) => {
+            assert.ifError(error);
+            assert.ok(req.oauth.bearerToken);
+            done();
+        });
+    });
+
+    it("test oauth MW - deviceId does not match", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = buildReq("4444444444");
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+
+    it("test oauth MW - deviceId on the token but no header", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = buildReq(undefined);
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+
+    it("test oauth MW - no deviceId on the token, check is skipped", (done) => {
+        let functionMw = mw(buildConfiguration(undefined));
+        let req = buildReq("5555555555");
+        functionMw(req, res, (error) => {
+            assert.ifError(error);
+            assert.ok(req.oauth.bearerToken);
+            done();
+        });
+    });
+
+    it("test oauth MW - null deviceId on the token, check is skipped", (done) => {
+        let functionMw = mw(buildConfiguration(null));
+        let req = buildReq("5555555555");
+        functionMw(req, res, (error) => {
+            assert.ifError(error);
+            assert.ok(req.oauth.bearerToken);
+            done();
+        });
+    });
+
+    // turns the check off at registry.custom.gateway.value.oauth
+    let turnCheckOff = (req, deviceIdCheck) => {
+        req.soajs.registry.custom = {
+            "gateway": {
+                "value": {
+                    "oauth": {
+                        "deviceIdCheck": deviceIdCheck
+                    }
+                }
+            }
+        };
+        return req;
+    };
+
+    it("test oauth MW - deviceId mismatch but check turned off at registry", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = turnCheckOff(buildReq("4444444444"), false);
+        functionMw(req, res, (error) => {
+            assert.ifError(error);
+            assert.ok(req.oauth.bearerToken);
+            done();
+        });
+    });
+
+    it("test oauth MW - deviceId mismatch and check explicitly turned on at registry", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = turnCheckOff(buildReq("4444444444"), true);
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+
+    it("test oauth MW - only false turns the check off, not a truthy value", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = turnCheckOff(buildReq("4444444444"), "false");
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+
+    it("test oauth MW - empty custom registry leaves the check on", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = buildReq("4444444444");
+        req.soajs.registry.custom = {};
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+});