scimgateway 4.1.15 → 4.2.0

package/README.md

@@ -16,9 +16,10 @@ Validated through IdP's:
   
 Latest news:  
 
+- Authentication PassThrough letting plugin pass authentication directly to endpoint for avoid maintaining secrets at the gateway. Kubernetes health checks and shutdown handler support
 - **BREAKING**: [SCIM Stream](https://elshaug.xyz/docs/scim-stream) is the modern way of user provisioning letting clients subscribe to messages instead of traditional IGA top-down provisioning. SCIM Stream includes **SCIM Stream Gateway**, the next generation SCIM Gateway that supports message subscription and automated provisioning
 - Supports OAuth Client Credentials authentication
-- Major version v4.0.0. getUsers() and getGroups() replacing some deprecated methods. No limitations on filtering/sorting. Admin user access can be linked to specific baseEntities. New MongoDB plugin  
+- Major version v4.0.0. getUsers() and getGroups() replacing some deprecated methods. No limitations on filtering/sorting. Admin user access can be linked to specific baseEntities. New MongoDB plugin
 - ipAllowList for restricting access to allowlisted IP addresses or subnets e.g. Azure AD IP-range  
 - General LDAP plugin configured for Active Directory  
 - [PlugSSO](https://elshaug.xyz/docs/plugsso) using SCIM Gateway
@@ -291,7 +292,12 @@ Below shows an example of config\plugin-saphana.json
 	        "to": null,
 	        "cc": null
 	      }
-	    }
+	    },
+        "kubernetes": {
+          "enabled": false,
+          "shutdownTimeout": 15000,
+          "forceExitTimeout": 1000
+        }
 	  },
 	  "endpoint": {
 	    "host": "hostname",
@@ -305,7 +311,7 @@ Below shows an example of config\plugin-saphana.json
 
 Configuration file have two main JSON objects: `scimgateway` and `endpoint`  
 
-Definitions in `scimgateway` object have fixed attributes, but values can be modified. This object is used by the core functionality of the SCIM Gateway.  
+Definitions in `scimgateway` object have fixed attributes, but values can be modified. Sections not used/configured can be removed. This object is used by the core functionality of the SCIM Gateway.  
 
 Definitions in `endpoint` object are customized according to our plugin code. Plugin typically need this information for communicating with endpoint  
 
@@ -408,6 +414,11 @@ Definitions in `endpoint` object are customized according to our plugin code. Pl
 - **emailOnError.smtp.to** - Comma separated list of recipients email addresses e.g: "someone@example.com"
 - **emailOnError.smtp.cc** - Comma separated list of cc email addresses
 
+- **kubernetes** - Enable Kubernetes support for healthchecks and graceful shutdown.
+- **kubernetes.enabled** - true or false, true will enable Kubernets health checks and shutdown handler
+- **kubernetes.shutdownTimeout** - Number of milliseconds to wait before shutting down (default 15000).
+- **kubernetes.forceExitTimeout** - Number of milliseconds before forceful exiting (default 1000).
+
 - **endpoint** - Contains endpoint specific configuration according to our **plugin code**.    
  
 #### Configuration notes
@@ -1040,12 +1051,13 @@ Plugins should have following initialization:
 	let validScimAttr = [] // empty array - all attrbutes are supported by endpoint
 	// add any external config process.env and process.file
 	config = scimgateway.processExtConfig(pluginName, config)
+    scimgateway.authPassThroughAllowed = false
 	// mandatory plugin initialization - end
 
 
 ### getUsers  
 
-	scimgateway.getUsers = async (baseEntity, getObj, attributes) => {
+	scimgateway.getUsers = async (baseEntity, getObj, attributes, ctx) => {
 	    let ret = {
 	        "Resources": [],
 	        "totalResults": null
@@ -1067,7 +1079,7 @@ ret.totalResults = if supporting pagination, then it should be set to the total
 
 ### deleteUser  
 
-	scimgateway.deleteUser = async (baseEntity, id) => {
+	scimgateway.deleteUser = async (baseEntity, id, ctx) => {
 		...
 		return null
 	} 
@@ -1077,7 +1089,7 @@ ret.totalResults = if supporting pagination, then it should be set to the total
 
 ### modifyUser  
 
-	scimgateway.modifyUser = async (baseEntity, id, attrObj) => {
+	scimgateway.modifyUser = async (baseEntity, id, attrObj, ctx) => {
 		...
 		return null
 	} 
@@ -1090,7 +1102,7 @@ Note, multi-value attributes excluding user attribute 'groups' are customized fr
 
 ### getGroups  
 
-	scimgateway.getGroups = async (baseEntity, getObj, attributes) => {
+	scimgateway.getGroups = async (baseEntity, getObj, attributes, ctx) => {
 	    let ret = {
 	        "Resources": [],
 	        "totalResults": null
@@ -1112,7 +1124,7 @@ ret.totalResults = if supporting pagination, then it should be set to the total
 
 
 ### createGroup  
-	scimgateway.createGroup = async (baseEntity, groupObj) => {
+	scimgateway.createGroup = async (baseEntity, groupObj, ctx) => {
 		...
 	    return null
 	})
@@ -1122,7 +1134,7 @@ groupObj.displayName contains the group name to be created
 * return null: null if OK, else throw error  
 
 ### deleteGroup  
-	scimgateway.deleteGroup = async (baseEntity, id) => {
+	scimgateway.deleteGroup = async (baseEntity, id, ctx) => {
 		...
 	    return null
 	}
@@ -1132,7 +1144,7 @@ groupObj.displayName contains the group name to be created
 
 ### modifyGroup  
 
-	scimgateway.modifyGroup = async (baseEntity, id, attrObj) => {
+	scimgateway.modifyGroup = async (baseEntity, id, attrObj, ctx) => {
 		...
 	    return null
 	}
@@ -1153,11 +1165,27 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 
 ## Change log  
 
+### v4.2.0  
+
+[Added]  
+
+- Kubernetes health checks and shutdown handler support 
+
+    Plugin configuration prerequisite: **kubernetes.enabled=true**      
+
+        "kubernetes": {
+          "enabled": true,
+          "shutdownTimeout": 15000,
+          "forceExitTimeout": 1000
+        }
+
+    **Thanks to Kevin Osborn**
+
 ### v4.1.15  
 
 [Added]  
 
-- authPassThrough for passing the authentication directly to plugin without being processed by scimgateway 
+- Authentication PassThrough for passing the authentication directly to plugin without being processed by scimgateway. Plugin can then pass this authentication to endpoint for avoid maintaining secrets at the gateway.   
 
     Plugin configuration prerequisites: **auth.passThrough.enabled=true**      
 
@@ -1182,6 +1210,7 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
         scimgateway.getUsers = async (baseEntity, getObj, attributes, ctx)
         // tip, see provided example plugins
 
+    **Thanks to Kevin Osborn**
 
 ### v4.1.14  
 

package/config/plugin-api.json

@@ -87,6 +87,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/config/plugin-azure-ad.json

@@ -87,6 +87,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/config/plugin-forwardinc.json

@@ -87,6 +87,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/config/plugin-ldap.json

@@ -87,6 +87,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/config/plugin-loki.json

@@ -87,6 +87,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/config/plugin-mongodb.json

@@ -93,6 +93,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/config/plugin-mssql.json

@@ -87,6 +87,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/config/plugin-saphana.json

@@ -87,6 +87,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/config/plugin-scim.json

@@ -87,6 +87,11 @@
         "to": null,
         "cc": null
       }
+    },
+    "kubernetes": {
+      "enabled": false,
+      "shutdownTimeout": 15000,
+      "forceExitTimeout": 1000
     }
   },
   "endpoint": {

package/lib/scimgateway.js

@@ -26,6 +26,7 @@ const callsite = require('callsite')
 const utils = require('../lib/utils')
 const countries = require('../lib/countries')
 const { createChecker } = require('is-in-subnet')
+const { createTerminus } = require('@godaddy/terminus')
 require('events').EventEmitter.prototype._maxListeners = Infinity
 
 /**
@@ -82,6 +83,7 @@ const ScimGateway = function () {
   if (!config.certificate.pfx) config.certificate.pfx = {}
   if (!config.emailOnError) config.emailOnError = {}
   if (!config.emailOnError.smtp) config.emailOnError.smtp = {}
+  if (!config.kubernetes) config.kubernetes = {}
 
   if (config.ipAllowList && Array.isArray(config.ipAllowList) && config.ipAllowList.length > 0) {
     ipAllowListChecker = createChecker(config.ipAllowList)
@@ -491,7 +493,7 @@ const ScimGateway = function () {
     const obj = config.auth.passThrough
     if (obj.baseEntities) {
       if (Array.isArray(obj.baseEntities) && obj.baseEntities.length > 0) {
-        if (!baseEntity || !obj.baseEntities.includes(baseEntity)) throw new Error(`baseEntity=${baseEntity} not allowed for passTrhough according to passTrhough configuration baseEntitites=${obj.baseEntities}`)
+        if (!baseEntity || !obj.baseEntities.includes(baseEntity)) throw new Error(`baseEntity=${baseEntity} not allowed for passThrough according to passThrough configuration baseEntitites=${obj.baseEntities}`)
       }
     }
     if (obj.readOnly === true && method !== 'GET') throw new Error('only allowing readOnly for passThrough according to passThrough configuration readOnly=true')
@@ -1768,6 +1770,45 @@ const ScimGateway = function () {
     }
   }
 
+  function onSignal () {
+    logger.info('server is starting cleanup')
+    return Promise.all([
+      // your clean logic, like closing database connections
+    ])
+  }
+
+  function onShutdown () {
+    logger.info('cleanup finished, server is shutting down')
+  }
+
+  function beforeShutdown () {
+    return new Promise(resolve => {
+      setTimeout(resolve, config.kubernetes.shutdownTimeout || 15000)
+    })
+  }
+
+  function healthCheck () {
+    return Promise.resolve(
+      // optionally include a resolve value to be included as
+      // info in the health check response
+    )
+  }
+  const options = {
+    // health check options
+    healthChecks: {
+      '/healthcheck': healthCheck, // a function returning a promise indicating service health,
+      verbatim: true // [optional = false] use object returned from /healthcheck verbatim in response
+    },
+
+    // cleanup options
+    timeout: config.kubernetes?.forceExitTimeout || 1000, // [optional = 1000] number of milliseconds before forceful exiting
+    beforeShutdown, // [optional] called before the HTTP server starts its shutdown
+    onSignal, // [optional] cleanup function, returning a promise (used to be onSigterm)
+    onShutdown // [optional] called right before exiting
+  }
+
+  if (config.kubernetes.enabled) createTerminus(server, options)
+
   // set loglevel according to config
   const arrValidLevel = ['silly', 'debug', 'verbose', 'info', 'warn', 'error']
   for (let i = 0; i < logger.transports.length; i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scimgateway",
-  "version": "4.1.15",
+  "version": "4.2.0",
   "description": "Using SCIM protocol as a gateway for user provisioning to other endpoints",
   "author": "Jarle Elshaug <jarle.elshaug@gmail.com> (https://elshaug.xyz)",
   "homepage": "https://elshaug.xyz",
@@ -32,6 +32,7 @@
     "node": ">=7.6.0"
   },
   "dependencies": {
+    "@godaddy/terminus": "^4.11.2",
     "callsite": "^1.0.0",
     "dot-object": "^2.1.4",
     "https-proxy-agent": "^5.0.1",