scimgateway 4.1.15 → 4.2.1

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,35 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 
 ## Change log  
 
+### v4.2.1  
+
+[Fixed]  
+
+- plugin-azure-ad createUser failed when manager was included
+- plugin-ldap slow when not using group/groupBase configuration
+
+
+### 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 +1218,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/plugin-azure-ad.js

@@ -243,11 +243,15 @@ scimgateway.createUser = async (baseEntity, userObj, ctx) => {
   const action = 'createUser'
   scimgateway.logger.debug(`${pluginName}[${baseEntity}] handling "${action}" userObj=${JSON.stringify(userObj)}`)
 
-  const attrObj = {}
+  const addonObj = {}
   if (userObj.servicePlan) {
-    attrObj.servicePlan = userObj.servicePlan // will be included in a modifyuser
+    addonObj.servicePlan = userObj.servicePlan
     delete userObj.servicePlan
   }
+  if (userObj.manager) {
+    addonObj.manager = userObj.manager
+    delete userObj.manager
+  }
 
   const method = 'POST'
   const path = '/users'
@@ -255,8 +259,8 @@ scimgateway.createUser = async (baseEntity, userObj, ctx) => {
 
   try {
     await doRequest(baseEntity, method, path, body)
-    if (attrObj.servicePlan) {
-      await scimgateway.modifyUser(baseEntity, userObj.userName, attrObj, ctx)
+    if (Object.keys(addonObj).length > 0) {
+      await scimgateway.modifyUser(baseEntity, userObj.userName, addonObj, ctx) // manager, servicePlan
       return null
     } else return (null)
   } catch (err) {

package/lib/plugin-ldap.js

@@ -240,7 +240,7 @@ scimgateway.getUsers = async (baseEntity, getObj, attributes, ctx) => {
 
       if (user.memberOf) {
         if (!config.map.group) user.memberOf = [] // empty any values
-        else if (config.useSID_id || config.useGUID_id) { // Active Directory - convert memberOf having dn values to objectSid/objectGUID
+        if (config.useSID_id || config.useGUID_id) { // Active Directory - convert memberOf having dn values to objectSid/objectGUID
           const arr = []
           try {
             if (Array.isArray(user.memberOf)) {
@@ -261,7 +261,9 @@ scimgateway.getUsers = async (baseEntity, getObj, attributes, ctx) => {
         }
       }
 
-      return scimgateway.endpointMapper('inbound', user, config.map.user)[0] // endpoint attribute naming => SCIM
+      const scimObj = scimgateway.endpointMapper('inbound', user, config.map.user)[0] // endpoint attribute naming => SCIM
+      if (!scimObj.groups) scimObj.groups = []
+      return scimObj
     }))
   } catch (err) {
     throw new Error(`${action} error: ${err.message}`)
@@ -509,8 +511,8 @@ scimgateway.getGroups = async (baseEntity, getObj, attributes, ctx) => {
     totalResults: null
   }
 
-  if (!config.map.group) { // not using groups
-    scimgateway.logger.debug(`${pluginName}[${baseEntity}] "${action}" stopped - missing configuration endpoint.map.group`)
+  if (!config.map.group || !config.entity[baseEntity].ldap.groupBase) { // not using groups
+    scimgateway.logger.debug(`${pluginName}[${baseEntity}] "${action}" stopped - missing configuration endpoint.map.group or groupBase`)
     return result
   }
 

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++) {
@@ -2360,7 +2401,7 @@ ScimGateway.prototype.endpointMapper = function endpointMapper (direction, parse
         else dotKey = `${dotPath}.${key}`
         if (direction === 'outbound') { // outbound
           if (obj[key] === '') obj[key] = null
-          if (dotMap[dotKey] && dotMap[`${dotKey}.type`]) {
+          if (dotMap[`${dotKey}.type`]) {
             const type = dotMap[`${dotKey}.type`].toLowerCase()
             if (type === 'boolean' && obj[key].constructor === String) {
               if ((obj[key]).toLowerCase() === 'true') obj[key] = true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scimgateway",
-  "version": "4.1.15",
+  "version": "4.2.1",
   "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",