scimgateway 6.1.20 → 6.2.1

package/README.md

@@ -17,6 +17,7 @@
 
 Latest news:  
 
+- New `plugin-generic` replacing previous `plugin-scim`. This new plugin use the endpointMapper for flexible attribute mapping and also supports the new mapper option `valueMap` (e.g., group filtering and mapping).
 - Now supports `GET /Roles` and `GET /Entitlements` endpoint requests, with corresponding user management via the standard SCIM `roles` and `entitlements` attributes. The Entra ID plugin uses `entitlements` for Entra ID licenses (read-only) and `roles` for Entra ID Permanent and Eligible roles (full management).
 - Bun binary build is now supported, allowing SCIM Gateway to be compiled into a single executable binary for simplified deployment and execution. SCIM Gateway can now run as an ES module (TypeScript) in Node.js.
 - Major release **v6.0.0** introduces changes to API method responses (not SCIM-related) and a new method `publicApi()` for handling public path `/pub/api` requests with no authentication required. In addition, the configuration option `bearerJwtAzure.tenantIdGUID` has been replaced by `bearerJwt.azureTenantId`. See the version history for details.
@@ -61,7 +62,7 @@ The following fully functional plugins are included for demonstration and produc
 | **Loki** | NoSQL Database | Transforms the SCIM Gateway into a standalone SCIM endpoint utilizing the internal [LokiJS](https://github.com/techfort/LokiJS) database. Includes two test users and groups |
 | **MongoDB** | NoSQL Database | Similar to the Loki plugin, but using an externally managed MongoDB database, showcasing multi-tenant and multi-endpoint capabilities via `baseEntity` |
 | **Entra ID** | REST Webservices | Entra ID user provisioning via Microsoft Graph API |
-| **SCIM** | REST Webservice | Using plugin Loki as a SCIM provisioning endpoint. May become a SCIM version-gateway (e.g., 1.1 => 2.0) |
+| **Generic** | REST Webservice | Generic template plugin configured to use plugin-loki as a SCIM provisioning endpoint. Supports the endpointMapper `valueMap` option for allowlisting and mapping (e.g., groups). Can also be used as a SCIM version gateway (e.g., 1.1 => 2.0) |
 | **API** | REST Webservices | A non-SCIM plugin demonstrating API Gateway functionality for custom REST specifications |
 | **Soap** | SOAP Webservice | Demonstrates user provisioning to a SOAP-based endpoint with example WSDLs |
 | **MSSQL** | Database | Demonstrates user provisioning to an MSSQL database |
@@ -1304,12 +1305,58 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 
 ## Change log
 
+### v6.2.1
+
+[Fixed]
+
+- `HelperRest`: fixed some minor log cosmetics introduced in v6.2.0
+
+### v6.2.0
+
+[Fixed]
+
+- `HelperRest`: failed on Bun v1.3.14 due to stricter compliance with Fetch standards.
+
+[Improved]
+
+- New `plugin-generic` replacing previous `plugin-scim`. This new plugin use the endpointMapper for flexible attribute mapping and also supports the new mapper option `valueMap` (e.g., group filtering and mapping). The default configuration uses one-to-one SCIM mapping, with plugin-loki as the target SCIM endpoint.
+- endpointMapper now supports the `valueMap` option
+
+	Example configuration:
+
+		"map": {
+		  "group": {
+		    ...
+		    "displayName": {
+		      "mapTo": "displayName",
+		      "type": "string",
+		      "valueMap": {
+		        "outboundEndpointGrp1": "inboundScimGrp1",
+		        "Employees": "Admins"
+		      }
+		    },
+		    ...
+		  }
+		  ...
+		}
+
+	Using the above settings restricts the client using SCIM Gateway with regard to group management.
+	The client will only see and be able to manage groups with SCIM names "inboundScimGrp1" and "Admins",
+	if their mapped counterparts exist at the target endpoint as "outboundEndpointGrp1" and "Employees".
+
+	Use case:
+
+	- Allowlisting specific groups or user objects that includes attribute mapping having the valueMap option configured.
+	- Supporting different inbound/outbound names (e.g., Entra ID group provisioning to SCIM Gateway).
+
+
 ### v6.1.20
 
 [Fixed]
 
 - plugin-entra-id: Roles introduced in v6.1.19 were missing when retrieving a single user.
 
+
 ### v6.1.19
 
 [Fixed]

package/config/{plugin-scim.json → plugin-generic.json}

@@ -156,6 +156,66 @@
           }
         }
       }
+    },
+    "map": {
+      "group": {
+        "id": {
+          "mapTo": "id",
+          "type": "string"
+        },
+        "displayName": {
+          "mapTo": "displayName",
+          "type": "string",
+          "valueMap": {}
+        },
+        "members": {
+          "mapTo": "members",
+          "type": "complexArray"
+        }
+      },
+      "user": {
+        "id": {
+          "mapTo": "id",
+          "type": "string"
+        },
+        "userName": {
+          "mapTo": "userName",
+          "type": "string"
+        },
+        "active": {
+          "mapTo": "active",
+          "type": "boolean"
+        },
+        "password": {
+          "mapTo": "password",
+          "type": "string"
+        },
+        "title": {
+          "mapTo": "title",
+          "type": "string"
+        },
+        "name": {
+          "mapTo": "name",
+          "type": "complexObject",
+          "subAttributes": []
+        },
+        "emails": {
+          "mapTo": "emails",
+          "type": "complexArray"
+        },
+        "phoneNumbers": {
+          "mapTo": "phoneNumbers",
+          "type": "complexArray"
+        },
+        "roles": {
+          "mapTo": "roles",
+          "type": "complexArray"
+        },
+        "entitlements": {
+          "mapTo": "entitlements",
+          "type": "complexArray"
+        }
+      }
     }
   }
 }

package/index.ts

@@ -12,7 +12,7 @@
 //
 
 // start one or more plugins:
-// import './lib/plugin-scim.ts'
+// import './lib/plugin-generic.ts'
 // import './lib/plugin-entra-id.ts'
 // import './lib/plugin-ldap.ts'
 // import './lib/plugin-mongodb.ts'

package/lib/helper-rest.ts

@@ -435,10 +435,9 @@ export class HelperRest {
   private async getServiceClient(baseEntity: string, connectionObj: Record<string, any>, method: string, path: string, opt?: any, ctx?: any) {
     const action = 'getServiceClient'
     if (typeof connectionObj !== 'object' || connectionObj === null) connectionObj = {}
-    let urlObj: any
     if (!path) path = ''
     try {
-      urlObj = new URL(path)
+      new URL(path)
     } catch (err) {
       //
       // path (no url) - default approach and client will be cached based on config
@@ -473,18 +472,12 @@ export class HelperRest {
           const err = new Error(`missing connection configuration: baseUrls`)
           throw err
         }
-        urlObj = new URL(connectionObj.baseUrls[0])
         const param: any = {
           baseUrl: connectionObj.baseUrls[0],
           options: {
-            json: true, // json-object response instead of string
             headers: {
               Accept: 'application/json',
             },
-            host: urlObj.hostname,
-            port: urlObj.port, // null if https and 443 defined in url
-            protocol: urlObj.protocol, // http: or https:
-            // 'method' and 'path' added at the end
           },
         }
 
@@ -567,16 +560,9 @@ export class HelperRest {
       }
       const cli: any = structuredClone(this._serviceClient[baseEntity]) // client ready
 
-      // failover support
-      path = this._serviceClient[baseEntity].baseUrl + path
-      urlObj = new URL(path)
-      cli.options.host = urlObj.hostname
-      cli.options.port = urlObj.port
-      cli.options.protocol = urlObj.protocol
-
-      // adding none static
       cli.options.method = method
-      cli.options.path = `${urlObj.pathname}${urlObj.search}`
+      cli.options.url = this._serviceClient[baseEntity].baseUrl + path // failover supported
+
       if (opt) {
         if (opt?.connection) delete opt.connection // only used for internal connection options
         cli.options = utils.extendObj(cli.options, opt) // merge with argument options
@@ -589,15 +575,11 @@ export class HelperRest {
     //
     this.scimgateway.logDebug(baseEntity, `${action}: Using raw client`)
     let options: any = {
-      json: true,
       headers: {
         Accept: 'application/json',
       },
-      host: urlObj.hostname,
-      port: urlObj.port,
-      protocol: urlObj.protocol,
       method: method,
-      path: urlObj.pathname + urlObj.search,
+      url: path,
     }
 
     // proxy
@@ -646,12 +628,13 @@ export class HelperRest {
   **/
   private async doRequestHandler(baseEntity: string, method: string, path: string, body?: any, ctx?: any, opt?: any, retryCount?: number): Promise<any> {
     const connectionObj = this.config_entity[baseEntity]?.connection ?? {}
+    let options: Record<any, any> = {}
     let retryAfter = 0
     try {
       const controller = new AbortController()
       const signal = controller.signal
       const cli = await this.getServiceClient(baseEntity, connectionObj, method, path, opt, ctx)
-      const options = cli.options
+      options = cli.options
       const timeout = setTimeout(() => controller.abort(), options.abortTimeout ? options.abortTimeout * 1000 : this.idleTimeout * 1000) // 120 seconds default abort timeout
       options.signal = signal
 
@@ -676,34 +659,33 @@ export class HelperRest {
           options.body = dataString
         } else if (options.headers) delete options.headers['Content-Type']
 
-        let url = `${options.protocol}//${options.host}${options.port ? ':' + options.port : ''}${options.path}`
-        if (this._serviceClient[baseEntity]?.nextLink[url]) {
+        if (this._serviceClient[baseEntity]?.nextLink[options.url]) {
           if (ctx?.paging?.startIndex && ctx.paging.startIndex > 1) {
-            if (ctx.paging.startIndex === this._serviceClient[baseEntity]?.nextLink[url].startIndex) {
-              url = this._serviceClient[baseEntity]?.nextLink[url]['@odata.nextLink']
+            if (ctx.paging.startIndex === this._serviceClient[baseEntity]?.nextLink[options.url].startIndex) {
+              options.url = this._serviceClient[baseEntity]?.nextLink[options.url]['@odata.nextLink']
             } else {
               if (!ctx) ctx = {}
               if (!ctx.paging) ctx.paging = {}
-              if (this._serviceClient[baseEntity]?.nextLink[url].totalResults
-                && ctx.paging.startIndex > this._serviceClient[baseEntity]?.nextLink[url].totalResults) {
-                ctx.paging.totalResults = this._serviceClient[baseEntity]?.nextLink[url].totalResults
+              if (this._serviceClient[baseEntity]?.nextLink[options.url].totalResults
+                && ctx.paging.startIndex > this._serviceClient[baseEntity]?.nextLink[options.url].totalResults) {
+                ctx.paging.totalResults = this._serviceClient[baseEntity]?.nextLink[options.url].totalResults
                 return { body: { value: [] } }
               } else {
                 // reset the paging cursor - none expected startIndex sequence, using default none paged url
                 ctx.paging.startIndex = 1 // caller should check and return this new startIndex in final response
-                delete this._serviceClient[baseEntity].nextLink[url]
+                delete this._serviceClient[baseEntity].nextLink[options.url]
               }
             }
           }
         } else {
-          if (ctx?.paging?.startIndex > 1 && !this._serviceClient[baseEntity]?.nextLink[url]) { // no previous paging and invalid startIndex
+          if (ctx?.paging?.startIndex > 1 && !this._serviceClient[baseEntity]?.nextLink[options.url]) { // no previous paging and invalid startIndex
             ctx.paging.totalResults = ctx.paging.startIndex - 1
             return { body: { value: [] } }
           }
         }
 
         // execute request
-        const f = await fetch(url, options)
+        const f = await fetch(options.url, options)
         if (!f.status) throw new Error('Response missing status code')
 
         const result: any = {
@@ -728,7 +710,7 @@ export class HelperRest {
           }
           throw new Error(JSON.stringify(result))
         }
-        this.scimgateway.logDebug(baseEntity, `doRequest ${method} ${options.protocol}//${options.host}${(options.port ? `:${options.port}` : '')}${options.path} Body = ${JSON.stringify(body)} Response = ${JSON.stringify(result)}`)
+        this.scimgateway.logDebug(baseEntity, `doRequest ${method} ${options.url} Body = ${JSON.stringify(body)} Response = ${JSON.stringify(result)}`)
 
         // OData paging logic
         // client prerequisite for enabling doRequest() OData paging support (see plugin-entra-id):
@@ -761,7 +743,7 @@ export class HelperRest {
               ctx.paging.totalResults = totalResults
             }
           } else { // no more paging
-            const linkBase = decodeURIComponent(url.substring(0, url.indexOf('$skiptoken') - 1))
+            const linkBase = decodeURIComponent(options.url?.substring(0, options.url?.indexOf('$skiptoken') - 1))
             if (ctx?.paging?.startIndex && ctx.paging.startIndex > 1 && this._serviceClient[baseEntity]?.nextLink[linkBase]) {
               if (!this._serviceClient[baseEntity]?.nextLink[linkBase].isCount) { // final no count page
                 const itemsPerPage = result.body.value.length
@@ -816,8 +798,8 @@ export class HelperRest {
         }
       } else {
         if (statusCode === 404) { // not logged as error e.g. getUser-manager
-          this.scimgateway.logDebug(baseEntity, `doRequest ${method} ${path} Body = ${JSON.stringify(body)} Error Response = ${err.message}`)
-        } else this.scimgateway.logError(baseEntity, `doRequest ${method} ${path} Body = ${JSON.stringify(body)} Error Response = ${err.message}`)
+          this.scimgateway.logDebug(baseEntity, `doRequest ${method} ${options.url} Body = ${JSON.stringify(body)} Error Response = ${err.message}`)
+        } else this.scimgateway.logError(baseEntity, `doRequest ${method} ${options.url} Body = ${JSON.stringify(body)} Error Response = ${err.message}`)
         if (statusCode === 401) delete this._serviceClient[baseEntity]
         throw err
       }

package/lib/plugin-entra-id.ts

@@ -294,6 +294,7 @@ scimgateway.getUsers = async (baseEntity, getObj, attributes, ctx) => {
   if (!path) throw new Error(`${action} error: mandatory if-else logic not fully implemented`)
 
   if (path.includes('$count=true')) { // $count=true requires ConsistencyLevel
+    // note: when using $expand, the $count=true might be ignored by target endpoint and the ctx.paging.totalResults updated by doReqest() will be incremental
     if (!options.headers) options.headers = {}
     options.headers.ConsistencyLevel = 'eventual'
   }
@@ -730,6 +731,7 @@ scimgateway.getGroups = async (baseEntity, getObj, attributes, ctx) => {
   if (!path) throw new Error(`${action} error: mandatory if-else logic not fully implemented`)
 
   if (path.includes('$count=true')) { // $count=true requires ConsistencyLevel
+    // note: when using $expand, the $count=true might be ignored by target endpoint and the ctx.paging.totalResults updated by doReqest() will be incremental
     if (!options.headers) options.headers = {}
     options.headers.ConsistencyLevel = 'eventual'
   }
@@ -1357,7 +1359,6 @@ const getUserRoles = async (baseEntity: string, userId: string, groups: Record<s
   })
 
   const permanentRoles = rolesAssignments.permanent.filter((role: any) => Ids.includes(role.principalId)).map((role: any) => {
-    if (eligibleRoles.filter((r: any) => r.value === role.roleDefinitionId).length > 0) return null // eligible role activated becomes listed as permanent, skip those...
     const roleDef = roleDefs[role.roleDefinitionId]
     if (roleDef) {
       if (includeAssignmentId === true) return { type: 'Permanent', value: roleDef.id, display: roleDef.displayName, assignmentId: role.id }