scimgateway 5.5.1 → 5.5.3

package/README.md

@@ -42,7 +42,7 @@ Latest news:
 
 ## Overview  
 
-SCIM Gateway facilitates user management using the standardized REST-based SCIM 1.1 or 2.0 protocol, offering easier, more powerful, and consistent provisioning while avoiding vendor lock-in. Acting as a translator for incoming SCIM requests, the gateway seamlessly enables CRUD functionality (create, read, update, and delete) for users and groups. By implementing endpoint-specific protocols, it ensures provisioning across diverse destinations. With the gateway, your destinations effectively become SCIM endpoints, streamlining integration and simplifying user management.  
+SCIM Gateway facilitates user management using the standardized REST-based SCIM 1.1 or 2.0 protocol, offering easier, more powerful, and consistent provisioning while avoiding vendor lock-in. Acting as a translator for incoming SCIM requests, the gateway seamlessly enables CRUD functionality (create, read, update, and delete) for users and groups. By implementing endpoint-specific protocols, it ensures provisioning across diverse destinations. With the gateway, your destinations become SCIM-compatible interfaces, streamlining integration and simplifying user management.  
 
 
 ![](https://jelhub.github.io/images/ScimGateway.svg)
@@ -738,16 +738,16 @@ Example Entra ID (plugin-entra-id) using federated credentials:
 	    "options": {
 	      "tenantIdGUID": "<tenantId>",
 	      "fedCred": {
-	        "issuer": "<https://FQDN-scimgateway/oauth>",
+	        "issuer": "<https://FQDN-scimgateway>",
 	        "subject": "<entra id application object id - client id>",
 	        "name": "<entra id federated credentials unique name>"
 	      }
 	    }
 	  }
 	}
-	// Note: Federated credentials defined for the application in Entra ID must match the corresponding `issuer`, `subject`, and `name`
-	// example issuer: "https://scimgateway.my-company.com/oauth" and base URL must be reachable from the internet
-	// exampole name: "plugin-entra-id"
+  	// Note, fedCred configuration must match corresponding configuration in Entra ID Application - Certificates & Secrets - Federated credentials - scenario "Other issuer"	
+	// example issuer: "https://scimgateway.my-company.com" note, this scimgateway base URL must be reachable from the internet
+	// example name: "plugin-entra-id"
 
 
 Example using general OAuth:  
@@ -972,8 +972,6 @@ On Linux systems we may also run SCIM Gateway as a Docker image (using docker-co
 **docker-ce  
 docker-compose**
 
-
-
 - Install SCIM Gateway within your own package and copy provided docker files:
 
 		mkdir /opt/my-scimgateway  
@@ -988,6 +986,7 @@ docker-compose**
 	**DataDockerfile**   <== Handles volume mapping   
 	**docker-compose-debug.yml** <== Debugging  
 	**docker-compose-mssql.yml** <== Example including MSSQL docker image
+	**.dockerignore** <== Files to exclude from the build context
 
 - Create a scimgateway user on your Linux VM.   
 
@@ -1491,6 +1490,26 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 
 ## Change log
 
+### v5.5.3
+
+[Fixed]
+- Docker - fixed `docker build` error introduced in v5.5.0 (using bun.lock instead of binary bun.lockb)
+
+[Improved]
+- plugin-mssql - attribute externalId included
+- .dockerignore - new docker configuration file, contains files to be excluded from the build context
+
+### v5.5.2
+
+[Improved]
+
+- Entra ID Federated Identity Credentials introduced in v5.5.0, the issuer configuration should be scimgateway base URL  
+	old: `"issuer": "<https://FQDN-scimgateway>/oauth"`  
+	new: `"issuer": "<https://FQDN-scimgateway>"`  
+
+	Change log v5.5.0 have been corrected with the new issuer having base URL only
+	
+
 ### v5.5.1
 
 [Fixed]
@@ -1510,7 +1529,7 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 		  "options": {
 		    "tenantIdGUID": "<Entra ID tenantIdGUID",
 		    "fedCred": {
-		      "issuer": "<https://FQDN-scimgateway/oauth>",
+		      "issuer": "<https://FQDN-scimgateway>",
 		      "subject": "<entra id application object id - client id>",
 		      "name": "<entra id federated credentials unique name>"
 		    }
@@ -1524,14 +1543,14 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 		  "options": {
 		    "tenantIdGUID": "11111111-2222-3333-4444-555555555555",
 		    "fedCred": {
-		      "issuer": "https://scimgateway.my-company.com/oauth",
+		      "issuer": "https://scimgateway.my-company.com",
 		      "subject": "99999999-8888-7777-6666-555555555555",
 		      "name": "plugin-entra-id"
 		    }
 		  }
 		}
 
-	Note: Federated credentials defined for the application in Entra ID must match the corresponding `issuer`, `subject`, and `name` values defined in the SCIM Gateway endpoint configuration. An example of this can be using `plugin-entra-id` and other plugins that interact with endpoints or applications protected by Entra ID.
+	Note: Federated credentials (scenario "Other issuer") defined for the application in Entra ID must match the corresponding `issuer`, `subject`, and `name` values defined in the SCIM Gateway endpoint configuration. An example of this can be using `plugin-entra-id` and other plugins that interact with endpoints or applications protected by Entra ID.
 
 	Also note: SCIM Gateway must be reachable from the internet (as defined by the `issuer` URL). This requires allowing inbound internet communication — or alternatively, Azure Relay can be used for outbound-only communication.
 

package/config/docker/.dockerignore

@@ -0,0 +1,27 @@
+.DS_Store
+dist/
+client_deploy/
+typings/
+/typings.json
+/jsconfig.json
+/npm-debug.log
+/uml.txt
+/.dockerignore
+/docker-compose*.yml
+/Dockerfile
+/DataDockerfile
+/sqlserver_data/
+/node_modules/
+/.vscode/
+/dbinit/
+/logs/
+/config/docker
+/config/approles
+/config/resources
+/eslint.config.js
+/.travis.yml
+/.gitignore
+/.gitattributes
+/.git/
+/.github/
+/test/

package/config/docker/DataDockerfile

@@ -2,7 +2,7 @@
 # To run: docker run -d --name scimgateway-data -t scimgateway-data:latest
 
 FROM busybox:latest
-LABEL maintainer="Jeffrey Gilbert"
+LABEL maintainer="https://elshaug.xyz"
 
 RUN mkdir -p /home/scimgateway/config
 VOLUME /home/scimgateway/config

package/config/docker/Dockerfile

@@ -1,3 +1,5 @@
+# Thanks to Charles Watson <cwatsonx@costco.com> and Jeffrey Gilbert for the base of Docker implementation and inspiration.
+#
 # Depending on your system you  may need to prefix the commands below with sudo.
 #
 # To build:  docker build --force-rm=true -t <projectName>:1.0.0 .
@@ -14,7 +16,7 @@
 FROM oven/bun:slim AS base
 
 # Declare who maintains this Dockerfile
-LABEL maintainer="Charles Watson <cwatsonx@costco.com>"
+LABEL maintainer="https://elshaug.xyz"
 
 # Add a Process ID 1 Safety Net.  Specific to debian.
 ADD https://github.com/Yelp/dumb-init/releases/download/v1.2.0/dumb-init_1.2.0_amd64 /usr/local/bin/dumb-init
@@ -25,7 +27,7 @@ WORKDIR /home/scimgateway
 ENV NODE_HOME=/home/scimgateway
 
 # Add your project info
-ADD ./package.json ./bun.lockb $NODE_HOME
+ADD ./package.json ./bun.lock $NODE_HOME
 
 # Install dependencies (exclude test stuff for dependencies)
 RUN . ~/.bashrc && cd $NODE_HOME && bun install --production --frozen-lockfile

package/lib/helper-rest.ts

@@ -154,27 +154,9 @@ export class HelperRest {
 
           if (tenantIdGUID) { // Microsoft Entra ID
             if (this.config_entity[baseEntity]?.connection?.auth?.options?.fedCred?.issuer) { // federated credentials
-              const name = JSON.stringify(this.config_entity[baseEntity]?.connection?.auth?.options?.fedCred?.name) // ensure not using none valid json key
-              if (!this.scimgateway.jwk) this.scimgateway.jwk = {}
-              if (!this.scimgateway.jwk[baseEntity]) this.scimgateway.jwk[baseEntity] = {}
-              if (!this.scimgateway.jwk[baseEntity][name]) {
-                const { publicKey, privateKey } = await jose.generateKeyPair('RS256')
-                this.scimgateway.jwk[baseEntity][name] = { publicKey, privateKey }
-                const ttl = 5 * 60 // 5 minutes
-                ;(async () => {
-                  // rotate - delete JWK after 5 minutes, will be regenerated on next token request
-                  // entra id only lookup well-known uri and corresponding jwks_uri on token request validation if kid not found in entra cached JWKS
-                  setTimeout(async () => {
-                    delete this.scimgateway.jwk[baseEntity][name]
-                  }, ttl * 1000)
-                })()
-              }
-
-              this.scimgateway.jwk[baseEntity].issuer = this.config_entity[baseEntity]?.connection?.auth?.options?.fedCred?.issuer // updates .well-known
-
               const now = Date.now()
               const jwtPayload: jose.JWTPayload = {
-                iss: this.config_entity[baseEntity]?.connection?.auth?.options?.fedCred?.issuer, // entra id federated credentials issuer e.g. https://scimgateway.my-company.com/oauth
+                iss: this.config_entity[baseEntity]?.connection?.auth?.options?.fedCred?.issuer, // entra id federated credentials issuer - scimgateway base URL, e.g. https://scimgateway.my-company.com
                 sub: this.config_entity[baseEntity]?.connection?.auth?.options?.fedCred?.subject, // entra id application object id - client id
                 name: this.config_entity[baseEntity]?.connection?.auth?.options?.fedCred?.name, // entra id federated credentials unique name e.g. plugin-entra-id
                 aud: 'api://AzureADTokenExchange', // entra id federated credentials audience
@@ -188,7 +170,8 @@ export class HelperRest {
                 ...jwtPayload,
               }
 
-              const jwk = await jose.exportJWK(this.scimgateway.jwk[baseEntity][name].publicKey)
+              const { publicKey, privateKey } = await jose.generateKeyPair('RS256')
+              const jwk = await jose.exportJWK(publicKey)
               const kid = createHash('sha256') // kid required for JWKS
                 .update(JSON.stringify(jwk))
                 .digest('base64url')
@@ -206,8 +189,22 @@ export class HelperRest {
                 client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
                 client_assertion: await new jose.SignJWT(jwtClaims)
                   .setProtectedHeader(jwtHeaders)
-                  .sign(this.scimgateway.jwk[baseEntity][name].privateKey),
+                  .sign(privateKey),
+              }
+
+              // keep JWK for 5 minutes, will be regenerated on next token request
+              // entra id only lookup well-known uri and corresponding jwks_uri on token request validation if kid not found in entra cached JWKS
+              if (!this.scimgateway.jwk) this.scimgateway.jwk = {}
+              if (!this.scimgateway.jwk[kid]) {
+                this.scimgateway.jwk[kid] = { publicKey, privateKey }
+                const ttl = 5 * 60
+                ;(async () => {
+                  setTimeout(async () => {
+                    delete this.scimgateway.jwk[kid]
+                  }, ttl * 1000)
+                })()
               }
+              this.scimgateway.jwk.issuer = this.config_entity[baseEntity]?.connection?.auth?.options?.fedCred?.issuer // all baseEntities should use same issuer
             } else { // standard certificate
               if (!this.config_entity[baseEntity]?.connection?.auth?.options?.tls?.cert) {
                 throw new Error(`auth type '${this.config_entity[baseEntity]?.connection?.auth?.type}' - missing options.tls.key/cert configuration`)
@@ -918,13 +915,13 @@ export class HelperRest {
   * }
   * 
   * // Microsoft Entra ID - using Federated credentials
-  * // Note, fedCred configuration must match corresponding configuration in Entra ID Application - Federation credentials 
+  * // Note, fedCred configuration must match corresponding configuration in Entra ID Application - Certificates & Secrets - Federated credentials - scenario "Other issuer"
   * {
   *   "type": "oauthJwtBearer",
   *   "options": {
   *     "tenantIdGUID": "<Entra ID tenantIdGUID",
   *     "fedCred": {
-  *       "issuer": "<https://FQDN-scimgateway/oauth>", // e.g. https://scimgateway.my-company.com/oauth
+  *       "issuer": "<https://FQDN-scimgateway", // scimgateway base URL, e.g. https://scimgateway.my-company.com
   *       "subject": "<entra id application object id - client id>",
   *       "name": "<entra id federated credentials unique name>" // e.g. plugin-entra-id
   *     }

package/lib/plugin-mssql.ts

@@ -121,6 +121,7 @@ scimgateway.getUsers = async (baseEntity, getObj, attributes, ctx) => {
       for (const user of users) {
         const scimUser = {
           id: user.UserID.value ? user.UserID.value : undefined,
+          externalId: user.UserID.value ? user.UserID.value : undefined,
           userName: user.UserID.value ? user.UserID.value : undefined,
           active: user.Enabled.value === 'true' || false,
           name: {
@@ -292,6 +293,7 @@ scimgateway.getGroups = async (baseEntity, getObj, attributes, ctx) => {
       for (const group of groups) {
         const scimGroup: Record<string, any> = {
           id: group.GroupID.value ? group.GroupID.value : undefined,
+          externalId: group.GroupID.value ? group.GroupID.value : undefined,
           displayName: group.GroupID.value ? group.GroupID.value : undefined,
           active: group.Enabled.value === 'true' || false,
           members: [],

package/lib/scimgateway.ts

@@ -333,15 +333,17 @@ export class ScimGateway {
       pluginDir = '.' // only support running binary in current directory (path to binary can't be found)
       configDir = './config'
     }
-    const configFile = path.join(`${configDir}`, `${pluginName}.json`) // config name prefix same as pluging name prefix
+    const configFile = path.join(configDir, `${pluginName}.json`) // config name prefix same as pluging name prefix
     const gwName = path.basename(fileURLToPath(import.meta.url)).split('.')[0] // prefix of current file - using fileURLToPath because using "__filename" is not supported by nodejs typescript
     const gwPath = path.dirname(fileURLToPath(import.meta.url))
 
     this.config = {}
     // exposed outside class
+    this.gwName = gwName
     this.pluginName = pluginName
     this.configDir = configDir
     this.configFile = configFile
+    this.authPassThroughAllowed = false // set to true by plugin if using Auth PassThrough
     this.countries = (() => {
       try {
         return JSON.parse(fs.readFileSync(path.join(gwPath, 'countries.json')).toString())
@@ -382,14 +384,7 @@ export class ScimGateway {
       logger.error(`${gwName}[${pluginName}] stopping...`)
       throw (new Error('Using exception to stop further asynchronous code execution (ensure synchronous logger flush to logfile and exit program), please ignore this one...'))
     }
-
     this.logger = logger
-    // exposed to plugin
-    this.gwName = gwName
-    this.pluginName = pluginName
-    this.configDir = configDir
-    this.configFile = configFile
-    this.authPassThroughAllowed = false // set to true by plugin if using Auth PassThrough
 
     const oAuthTokenExpire = 3600 // seconds
     let pwErrCount = 0
@@ -486,7 +481,7 @@ export class ScimGateway {
       getMethod: 'getAppRoles',
     }
     /** handlers supported url paths */
-    const handlers = ['users', 'groups', 'bulk', 'serviceplans', 'approles', 'api', 'schemas', 'resourcetypes', 'serviceproviderconfig', 'serviceproviderconfigs', 'oauth', 'logger']
+    const handlers = ['users', 'groups', 'bulk', 'serviceplans', 'approles', 'api', 'schemas', 'resourcetypes', 'serviceproviderconfig', 'serviceproviderconfigs', 'oauth', '.well-known', 'logger']
 
     try {
       if (!fs.existsSync(configDir + '/wsdls')) fs.mkdirSync(configDir + '/wsdls')
@@ -972,53 +967,44 @@ export class ScimGateway {
       )
     }
 
-    // oauth well-known: /oauth/.well-known/openid-configuration
+    // oauth well-known: /.well-known/openid-configuration
     // this.jwk is managed by helper-rest oauthJwtBearer - Entra ID Federated Identity
-    // {issuer: <scimgateway-baseUrl>/oauth, <federated-identity-unique-name>: {privateKey, publicKey}}
-    // example issuer: https://scimgateway.my-company.com/oauth
+    // { issuer: <scimgateway-baseUrl>, kid: { privateKey, publicKey } }
+    // example issuer: https://scimgateway.my-company.com
     const getHandlerOauthWellKnown = async (ctx: Context) => {
-      const baseEntity = ctx.routeObj.baseEntity
-      logger.debug(`${gwName}[${pluginName}][${baseEntity}] [oauth] .well-known request`)
-
-      if (!this.jwk || !this.jwk[baseEntity] || !this.jwk[baseEntity].issuer) {
+      logger.debug(`${gwName}[${pluginName}] [oauth] .well-known request`)
+      if (!this.jwk || (Object.keys(this.jwk).length < 1)) {
         ctx.response.body = '{}'
         ctx.response.status = 200
         return ctx
       }
-
-      const issuer = this.jwk[baseEntity].issuer //  dynamic set by helper-rest oauthJwtBearer e.g. 'https://scimgateway.my-company.com/oauth'
+      const issuer = this.jwk.issuer
       let body = {
         issuer,
-        jwks_uri: issuer + '/certs',
+        jwks_uri: issuer + '/.well-known/jwks.json',
       }
       ctx.response.body = JSON.stringify(body)
       ctx.response.status = 200
     }
 
-    // oauth JWKS: /oauth/certs
+    // oauth JWKS: /.well-known/jwks.json
     // this.jwk is managed by helper-rest oauthJwtBearer - Entra ID Federated Identity
-    // {issuer: <scimgateway-baseUrl>/oauth, <federated-identity-unique-name>: {privateKey, publicKey}}
-    const getHandlerOauthCerts = async (ctx: Context) => {
-      const baseEntity = ctx.routeObj.baseEntity
-      logger.debug(`${gwName}[${pluginName}][${baseEntity}] [oauth] jwks_uri certs request`)
-
-      if (!this.jwk || !this.jwk[baseEntity]) {
+    // { issuer: <scimgateway-baseUrl>, kid: { privateKey, publicKey } }
+    const getHandlerOauthJwks = async (ctx: Context) => {
+      logger.debug(`${gwName}[${pluginName}] [oauth] jwks_uri request`)
+      if (!this.jwk || (Object.keys(this.jwk).length < 1)) {
         ctx.response.body = '{"keys":[]}'
         ctx.response.status = 200
         return ctx
       }
-
       const keys: Array<Record<string, any>> = []
-      for (const name in this.jwk[baseEntity]) {
-        const keyObj = this.jwk[baseEntity][name]
-        if (typeof keyObj !== 'object' || keyObj === null) continue // skip issuer
-        const jwk = await jose.exportJWK(this.jwk[baseEntity][name].publicKey)
-        jwk.kid = createHash('sha256') // needed for JWKS
-          .update(JSON.stringify(jwk))
-          .digest('base64url')
+      for (const kid in this.jwk) {
+        const keyObj = this.jwk[kid]
+        if (typeof keyObj !== 'object' || keyObj === null) continue
+        const jwk = await jose.exportJWK(this.jwk[kid].publicKey)
+        jwk.kid = kid // needed for JWKS
         keys.push(jwk)
       }
-
       let body = {
         keys,
       }
@@ -2673,13 +2659,13 @@ export class ScimGateway {
           return ctx
         }
       }
-      if (ctx.request.method === 'GET' && ctx.path.endsWith('/oauth/.well-known/openid-configuration')) {
+      if (ctx.request.method === 'GET' && ctx.path.endsWith('/.well-known/openid-configuration')) {
         await getHandlerOauthWellKnown(ctx)
         if (!ctx.response.status) ctx.response.status = 404
         return ctx
       }
-      if (ctx.request.method === 'GET' && ctx.path.endsWith('/oauth/certs')) {
-        await getHandlerOauthCerts(ctx)
+      if (ctx.request.method === 'GET' && ctx.path.endsWith('/.well-known/jwks.json')) {
+        await getHandlerOauthJwks(ctx)
         if (!ctx.response.status) ctx.response.status = 404
         return ctx
       }
@@ -3093,8 +3079,8 @@ export class ScimGateway {
             let request = new Request(new URL(req.url ?? '', `${protocol}://${req.headers.host}`), {
               method: req.method,
               headers: new Headers(req.headers as any),
+              // @ts-expect-error ignore incompatible types
               body: body,
-              // @ts-expect-error duplex not defined in RequestInit interface
               duplex: body ? 'half' : undefined,
             }) as Request & { raw: IncomingMessage }
             request.raw = req

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scimgateway",
-  "version": "5.5.1",
+  "version": "5.5.3",
   "type": "module",
   "description": "Using SCIM protocol as a gateway for user provisioning to other endpoints",
   "author": "Jarle Elshaug <jarle.elshaug@gmail.com> (https://elshaug.xyz)",