scimgateway 5.1.5 → 5.1.6

package/README.md

@@ -465,7 +465,7 @@ Definitions in `endpoint` object are customized according to our plugin code. Pl
 
 - **endpoint** - Contains endpoint specific configuration according to customized **plugin code**. 
 
-#### Configuration notes
+### Configuration notes - general
 
 - Custom Schemas, ServiceProviderConfig and ResourceType can be used if `./lib/scimdef-v2.json or scimdef-v1.json` exists. Original scimdef-v2.json/scimdef-v1.json can be copied from node_modules/scimgateway/lib to your plugin/lib and customized.
 - Using reverse proxy and we want ipAllowList and correct meta.location response, following headers must be set by proxy: `X-Forwarded-For`, `X-Forwarded-Proto` and `X-Forwarded-Host`  
@@ -521,88 +521,204 @@ Definitions in `endpoint` object are customized according to our plugin code. Pl
 		  "plugin-soap.endpoint.password": "secret"
 		}  
 
+### Configuration notes - Email, using Microsoft Exchange Online (ExO)
 
-- Email, using Microsoft Exchange Online (ExO)
-
-	- Entra ID application must have application permissions `Mail.Send`  
-	- To prevent the sending of emails from any defined mailboxes, an ExO `ApplicationAccessPolicy` must be defined through PowerShell.  
-	
-		First create a mail-enabled security-group that only includes those users (mailboxes) the application is allowed to send from  
-		Note, `mail enabled security group` cannot be created from portal, only from admin or admin.exchange console
-		  
-			##Connect to Exchange
-			Install-Module -Name ExchangeOnlineManagement
-			Connect-ExchangeOnline
-			 
-			##Create ApplicationAccessPolicy
-			New-ApplicationAccessPolicy -AppId <AppClientID> -PolicyScopeGroupId <MailEnabledSecurityGrpId> -AccessRight RestrictAccess -Description "Restrict app to specific mailboxes"
-
-- Email, using Google Workspace Gmail
-
-	- https://console.cloud.google.com
-		- IAM & Admin > Service Accounts > Create Service Account
-			- Name=email-sender  
-			- Create and Continue
-			- Grant this service account access to project - not needed
-			- Grant users access to this service - not needed  
-		- IAM & Admin > Service Accounts > "email-sender" account > Keys    
-			- Add Key > Create new key > JSON
-			- download json Service Account Key file, refere to configuration `email.auth.options.serviceAccountKeyFile`
-
-	- https://admin.google.com
-		- Security > Access and data control > API controls
-			- Manage Domain Wide Delegation > Add new
-			- Client ID = id of service account created
-			- OAuth scope = `https://www.googleapis.com/auth/gmail.send`  
-	 
-	- https://admin.google.com
-		- Billing > Subscriptions - verify Google Workspace license
-		- Directory > Users > "user"
-		- Licenses > Edit > enable Google Workspace license  
-		`email.emailOnError.from` mail address must have Google Workspace license
-
-- Gateway chainging and chainingBaseUrl configuration
-
-	By configuring the `chainingBaseUrl`, it is possible to chain multiple gateways in sequence, such as `gateway1->gateway2->gateway3->endpoint`. In this setup, gateway behave much like a reverse proxy, validating authorization at each step unless PassThrough mode is enabled. Chaining is also supported in stream subscriber mode
+- Entra ID application must have application permissions `Mail.Send`  
+- To prevent the sending of emails from any defined mailboxes, an ExO `ApplicationAccessPolicy` must be defined through PowerShell.  
 	
-		{
-		  "scimgateway": {
-		    ...
-		    "chainingBaseUrl": "https:\\gateway2:8880",
-		    ...
-		    "auth": {
-		      ...
-		      "passThrough": {
-		        "enabled": false,
-		        "readOnly": false,
-		        "baseEntities": []
-		      }
-			  ...
-		    }
-		  },
+	First create a mail-enabled security-group that only includes those users (mailboxes) the application is allowed to send from  
+	Note, `mail enabled security group` cannot be created from portal, only from admin or admin.exchange console
+			  
+		##Connect to Exchange
+		Install-Module -Name ExchangeOnlineManagement
+		Connect-ExchangeOnline
+		 
+		##Create ApplicationAccessPolicy
+		New-ApplicationAccessPolicy -AppId <AppClientID> -PolicyScopeGroupId <MailEnabledSecurityGrpId> -AccessRight RestrictAccess -Description "Restrict app to specific mailboxes"
+
+### Configuration notes - Email, using Google Workspace Gmail
+
+- https://console.cloud.google.com
+	- IAM & Admin > Service Accounts > Create Service Account
+		- Name=email-sender  
+		- Create and Continue
+		- Grant this service account access to project - not needed
+		- Grant users access to this service - not needed  
+	- IAM & Admin > Service Accounts > "email-sender" account > Keys    
+		- Add Key > Create new key > JSON
+		- download json Service Account Key file, refere to configuration `email.auth.options.serviceAccountKeyFile`
+
+- https://admin.google.com
+	- Security > Access and data control > API controls
+		- Manage Domain Wide Delegation > Add new
+		- Client ID = id of service account created
+		- OAuth scope = `https://www.googleapis.com/auth/gmail.send`  
+ 
+- https://admin.google.com
+	- Billing > Subscriptions - verify Google Workspace license
+	- Directory > Users > "user"
+	- Licenses > Edit > enable Google Workspace license  
+	`email.emailOnError.from` mail address must have Google Workspace license
+
+### Configuration notes - Gateway chainging and chainingBaseUrl
+
+By configuring the `chainingBaseUrl`, it is possible to chain multiple gateways in sequence, such as `gateway1->gateway2->gateway3->endpoint`. In this setup, gateway behave much like a reverse proxy, validating authorization at each step unless PassThrough mode is enabled. Chaining is also supported in stream subscriber mode
+
+	{
+	  "scimgateway": {
+	    ...
+	    "chainingBaseUrl": "https:\\gateway2:8880",
+	    ...
+	    "auth": {
+	      ...
+	      "passThrough": {
+	        "enabled": false,
+	        "readOnly": false,
+	        "baseEntities": []
+	      }
 		  ...
-		}
-	
-	
-	Using above configuration example on gateway1, incoming requests will be routed to `https:\\gateway2:8880`
+	    }
+	  },
+	  ...
+	}
+
+
+Using above configuration example on gateway1, incoming requests will be routed to `https:\\gateway2:8880`
+
+The plugin and its associated authentication configuration can mirror the setup running on the final gateway. However, in chaining mode, the plugin binary is used solely for initializing and configuring the gateway. This allows for the use of a simplified `plugin-<name>.ts` binary containing only the essential mandatory components:
 	
-	The plugin and its associated authentication configuration can mirror the setup running on the final gateway. However, in chaining mode, the plugin binary is used solely for initializing and configuring the gateway. This allows for the use of a simplified `plugin-<name>.ts` binary containing only the essential mandatory components:
-		
-		// start - mandatory plugin initialization
-		const ScimGateway: typeof import('scimgateway').ScimGateway = await (async () => {
-		  try {
-		    return (await import('scimgateway')).ScimGateway
-		  } catch (err) {
-		    const source = './scimgateway.ts'
-		    return (await import(source)).ScimGateway
-		  }
-		})()
-		const scimgateway = new ScimGateway()
-		const config = scimgateway.getConfig()
-		scimgateway.authPassThroughAllowed = false
-		// end - mandatory plugin initialization
+	// start - mandatory plugin initialization
+	const ScimGateway: typeof import('scimgateway').ScimGateway = await (async () => {
+	  try {
+	    return (await import('scimgateway')).ScimGateway
+	  } catch (err) {
+	    const source = './scimgateway.ts'
+	    return (await import(source)).ScimGateway
+	  }
+	})()
+	const scimgateway = new ScimGateway()
+	const config = scimgateway.getConfig()
+	scimgateway.authPassThroughAllowed = false
+	// end - mandatory plugin initialization
+
+Using `scimgateway.authPassThroughAllowed = true` and `plugin-<name>.json` configuration `scimgateway.auth.passThrough=true` enables Authentication PassTrhough
+
+### Configuration notes - HelperRest used by plugins  
+For REST endpoints, plugins may use HelperRest to simplify authentication and communication  
+doRequest() executes REST request and return response  
+`doRequest(<baseEntity>, <method>, <path>, <body>, <ctx>, <options>)`
+
+* baseEntity - 'undefined' if not used and must correspond with endpoint configuration that defines baseUrls and connection options.
+* method - GET, PATCH, PUT, DELETE
+* path - either full url or just the path that will be added to baseUrl. Using full url will override baseUrl. Using path is preferred because of auth caching logic and simplicity
+* body - optional body to be used	
+* ctx - optional, passing authorization header if Auth PassThrough is enabled
+* opt - optional, connection options that will extend/override any endpoint.entity.undefined.connection definitions
+
+Configuration showing connection settings:  
+
+	{
+	  "scimgateway": {
+	    ...
+	  }
+	  "endpoint": {
+	    "entity": {
+	      "undefined": {
+	        "connection": {
+	          "baseUrls": [],
+	          "auth": {
+	            "type": "xxx",
+	            "options": {
+				  ...
+				  "jwtPayload": {},
+				  "samlPayload": {},
+				  "tls": {} // files located in ./config/certs
+				}
+	          },
+	          "options": {
+			    "headers": {},
+	            "tls": {} // files located in ./config/certs
+	          },
+	          "proxy": {}
+	        }
+	      }
+	    }
+	  }
+	}
+
+
+* baseUrls - Endpoint URL. Several may be defined for failower. There are retry logic on connection failures
+* auth.type - defines authentication being used: `basic`, `oauth`, `token`, `bearer`, `oauthSamlBearer` or `oauthJwtBearer`
+* auth.options - for each valid type there are different options. tenantIdGUID is special for Entra ID and serviceAccountKeyFile is special for Google. Using these will simplify and reduce options to be included. Also note we do not need to include baseUrls when using tenantIdGUID/serviceAccountKeyFile as long as endpoint is Entra ID (Microsoft Graph) or Google.
+
+Example using basic auth:  
+
+	"connection": {
+	  "baseUrls": [
+		"https://localhost:8880"
+	  ],
+	  "auth": {
+		"type": "basic",
+		"options": {
+		  "username": "gwadmin",
+		  "password": "password"
+		}
+	  },
+	  "options": {
+		"tls": {
+		  "rejectUnauthorized": false,
+		  "ca": "ca.pem"
+		}
+	  }
+	}
+
+Example Entra ID (plugin-entra-id) using clientId/clientSecret:  
+
+	"connection": {
+	  "baseUrls": [],
+	  "auth": {
+		"type": "oauth",
+		"options": {
+		  "tenantIdGUID": "<tenantId>",
+		  "clientId": "<clientId",
+		  "clientSecret": "<clientSecret>"
+		}
+	  }
+	}
+
+Example Entra ID (plugin-entra-id) using certificate secret:  
+
+	"connection": {
+	  "baseUrls": [],
+	  "auth": {
+		"type": "oauth",
+		"options": {
+		  "tenantIdGUID": "<tenantId>",
+		  "clientId": "<clientId",
+		  "tls": {
+	        "key": "key.pem",
+	        "cert": "cert.pem"
+          }
+		}
+	  }
+	}
+
+Example using general OAuth:  
+
+	"connection": {
+	  "baseUrls": ["endpointUrl"],
+	  "auth": {
+		"type": "oauth",
+		"options": {
+		  "tokenUrl": "<tokenUrl>"
+		  "clientId": "<clientId",
+		  "clientSecret": "<clientSecret>"
+		}
+	  }
+	}
+
+Please see code editor method HelperRest doRequest() IntelliSense for type and option details
 
-	Using `scimgateway.authPassThroughAllowed = true` and `plugin-<name>.json` configuration `scimgateway.auth.passThrough=true` enables Authentication PassTrhough
 
 ## Manual startup    
 
@@ -1175,6 +1291,13 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 
 ## Change log  
 
+### v5.1.6
+
+[Improved]
+
+- HelperRest, payload/claims configuration now defined in auth.options.jwtPayload and auth.options.samlPayload. Previously all was defiend in auth.options
+- README configuration notes updated
+
 ### v5.1.5
 
 [Improved]
@@ -1205,7 +1328,7 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 		          "options": {
 		            "tenantIdGUID": "Entra ID Tenant ID (GUID)",
 		            "clientId": "<application clientId>",
-		            "certificate": { // files located in ./config/certs
+		            "tls": { // files located in ./config/certs
 		              "key": "key.pem",
 		              "cert": "cert.pem"
 		            }

package/lib/helper-rest.ts

@@ -42,7 +42,7 @@ export class HelperRest {
       if (this.config_entity[baseEntity]?.connection) {
         connectionFound = true
         const type = this.config_entity[baseEntity].connection?.auth?.type
-        if (type === 'oauthJwtBearer' || type === 'oauth') { // includes oauth because of email.auth.type
+        if (type === 'oauthJwtBearer' || type === 'oauth') {
           // set default baseUrls for Entra ID and Google if not already defined
           if (this.config_entity[baseEntity]?.connection?.auth?.options?.tenantIdGUID) { // Entra ID, setting baseUrls to graph
             if (!this.config_entity[baseEntity].connection.baseUrls) {
@@ -83,29 +83,32 @@ export class HelperRest {
 
     const action = 'getAccessToken'
 
+    const serviceAccountKeyFile = this.config_entity[baseEntity]?.connection?.auth?.options?.serviceAccountKeyFile
+    const tenantIdGUID = this.config_entity[baseEntity]?.connection?.auth?.options?.tenantIdGUID
     let tokenUrl: string
-    let form: object
+    let form: Record<string, any>
     let resource = ''
 
+    try {
+      const urlObj = new URL(this.config_entity[baseEntity].connection.baseUrls[0])
+      resource = urlObj.origin
+    } catch (err) { void 0 }
+    if (tenantIdGUID) {
+      tokenUrl = `https://login.microsoftonline.com/${tenantIdGUID}/oauth2/v2.0/token`
+      if (resource) this.config_entity[baseEntity].connection.auth.options.scope = resource + '/.default' // "https://graph.microsoft.com/.default"
+    } else tokenUrl = this.config_entity[baseEntity].connection.auth.options.tokenUrl
+
     try {
       switch (this.config_entity[baseEntity]?.connection?.auth?.type) {
         case 'oauth':
-          try {
-            const urlObj = new URL(this.config_entity[baseEntity].connection.baseUrls[0])
-            resource = urlObj.origin
-          } catch (err) { void 0 }
-          if (this.config_entity[baseEntity].connection.auth?.options?.tenantIdGUID) { // Azure
-            tokenUrl = `https://login.microsoftonline.com/${this.config_entity[baseEntity].connection.auth.options.tenantIdGUID}/oauth2/token`
-          } else {
-            tokenUrl = this.config_entity[baseEntity].connection.auth.options.tokenUrl
-          }
           form = {
             grant_type: 'client_credentials',
             client_id: this.config_entity[baseEntity].connection.auth.options.clientId,
             client_secret: this.config_entity[baseEntity].connection.auth.options.clientSecret,
-            scope: this.config_entity[baseEntity].connection.auth.options.scope || null,
-            resource: resource || null, // "https://graph.microsoft.com"
           }
+          if (this.config_entity[baseEntity].connection.auth.options.scope) form.scope = this.config_entity[baseEntity].connection.auth.options.scope // required using Entra ID /oauth2/v2.0/token
+          if (this.config_entity[baseEntity].connection.auth.options.resource) resource = this.config_entity[baseEntity].connection.auth.options.resource // required using Entra ID /oauth2/token
+
           break
 
         case 'token':
@@ -119,23 +122,26 @@ export class HelperRest {
         case 'oauthSamlBearer':
           tokenUrl = this.config_entity[baseEntity].connection.auth.options.tokenUrl
           const context = null
-          const cert = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.certificate.cert).toString()
-          const key = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.certificate.key).toString()
-
-          const issuer = `scimgateway/${this.scimgateway.pluginName}`
-          const lifetime = 3600
-          const clientId = this.config_entity[baseEntity].connection.auth.options.clientId
-          const nameId = this.config_entity[baseEntity].connection.auth.options.userId
-          const userIdentifierFormat = 'userName'
+          const cert = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.tls.cert).toString()
+          const key = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.tls.key).toString()
+
           const tokenEndpoint = tokenUrl
-          const audience = `scimgateway/${this.scimgateway.pluginName}`
           const delay = 1
 
+          // mandatory: clientId, companyId and nameId
+          const clientId = this.config_entity[baseEntity].connection.auth.options.samlPayload.clientId
+          const companyId = this.config_entity[baseEntity].connection.auth.options.samlPayload.companyId
+          const nameId = this.config_entity[baseEntity].connection.auth.options.samlPayload.nameId
+          const userIdentifierFormat = this.config_entity[baseEntity].connection.auth.options.samlPayload.userIdentifierFormat || 'userName'
+          const lifetime = this.config_entity[baseEntity].connection.auth.options.samlPayload.lifetime || 3600
+          const issuer = this.config_entity[baseEntity].connection.auth.options.samlPayload.clientId || `https://scimgateway.${this.scimgateway.pluginName}.com`
+          const audience = this.config_entity[baseEntity].connection.auth.options.samlPayload.audience || `scimgateway/${this.scimgateway.pluginName}`
+
           form = {
             token_url: tokenUrl,
             grant_type: 'urn:ietf:params:oauth:grant-type:saml2-bearer',
             client_id: clientId,
-            company_id: this.config_entity[baseEntity].connection.auth.options.companyId,
+            company_id: companyId,
             assertion: await samlAssertion.run(context, cert, key, issuer, lifetime, clientId, nameId, userIdentifierFormat, tokenEndpoint, audience, delay),
           }
           break
@@ -143,25 +149,21 @@ export class HelperRest {
         case 'oauthJwtBearer':
           let jwtClaims: jsonwebtoken.JwtPayload | Record<string, any> = {}
           let jwtOpts: jsonwebtoken.SignOptions = {}
-          const serviceAccountKeyFile = this.config_entity[baseEntity]?.connection?.auth?.options?.serviceAccountKeyFile
-          const tenantIdGUID = this.config_entity[baseEntity]?.connection?.auth?.options?.tenantIdGUID
 
-          if (tenantIdGUID) {
-            // Microsoft Entra ID
-            if (!this.config_entity[baseEntity]?.connection?.auth?.options?.certificate?.key || !this.config_entity[baseEntity]?.connection?.auth?.options?.certificate?.cert) {
-              throw new Error(`auth type '${this.config_entity[baseEntity]?.connection?.auth?.type}' - missing options.certificate.key/cert configuration`)
+          if (tenantIdGUID) { // Microsoft Entra ID
+            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`)
             }
-            tokenUrl = `https://login.microsoftonline.com/${tenantIdGUID}/oauth2/v2.0/token` // `https://login.microsoftonline.com/${tenantIdGUID}/oauth2/token`
-            let privateKey = this.config_entity[baseEntity]?.connection?.auth?.options?.certificate?._key || ''
-            let cert = this.config_entity[baseEntity]?.connection?.auth?.options?.certificate?._cert || ''
+            let privateKey = this.config_entity[baseEntity]?.connection?.auth?.options?.tls?._key || ''
+            let cert = this.config_entity[baseEntity]?.connection?.auth?.options?.tls?._cert || ''
             if (!privateKey || !cert) {
-              privateKey = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.certificate.key, 'utf-8') || ''
-              cert = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.certificate.cert, 'utf-8') || ''
-              if (privateKey) this.config_entity[baseEntity].connection.auth.options.certificate._key = privateKey
-              if (cert) this.config_entity[baseEntity].connection.auth.options.certificate._cert = cert
+              privateKey = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.tls.key, 'utf-8') || ''
+              cert = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.tls.cert, 'utf-8') || ''
+              if (privateKey) this.config_entity[baseEntity].connection.auth.options.tls._key = privateKey
+              if (cert) this.config_entity[baseEntity].connection.auth.options.tls._cert = cert
             }
             if (!privateKey || !cert) {
-              throw new Error(`auth type '${this.config_entity[baseEntity]?.connection?.auth?.type}' - missing options.certificate.key/cert file content`)
+              throw new Error(`auth type '${this.config_entity[baseEntity]?.connection?.auth?.type}' - missing options.tls.key/cert file content`)
             }
 
             const jwtPayload: jsonwebtoken.JwtPayload = {
@@ -199,23 +201,16 @@ export class HelperRest {
             }
             */
 
-            let scope = 'https://graph.microsoft.com/.default'
-            try {
-              const urlObj = new URL(this.config_entity[baseEntity].connection.baseUrls[0])
-              scope = urlObj.origin + '/.default' // for application exposed api's and included permissions use: api://${this.config_entity[baseEntity]?.connection?.auth?.options?.clientId}/.default
-            } catch (err) { void 0 }
-
             form = {
-              scope,
               grant_type: 'client_credentials',
+              scope: this.config_entity[baseEntity].connection.auth.options.scope, // "https://graph.microsoft.com/.default"
               client_id: this.config_entity[baseEntity]?.connection?.auth?.options?.clientId,
               client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
               client_assertion: jsonwebtoken.sign(jwtClaims, privateKey, jwtOpts),
             }
-          } else if (serviceAccountKeyFile) {
-            // Google - using Service Account key json-file
-            if (!this.config_entity[baseEntity]?.connection?.auth?.options?.scope || !this.config_entity[baseEntity]?.connection?.auth?.options?.subject) {
-              const err = new Error(`auth type '${this.config_entity[baseEntity]?.connection?.auth?.type}' - using auth.options 'serviceAccountKeyFile' requires mandatory configuration entity.${baseEntity}.connection.auth.options.scope/subject`)
+          } else if (serviceAccountKeyFile) { // Google - using Service Account key json-file
+            if (!this.config_entity[baseEntity]?.connection?.auth?.options?.jwtPayload?.scope || !this.config_entity[baseEntity]?.connection?.auth?.options?.jwtPayload?.subject) {
+              const err = new Error(`auth type '${this.config_entity[baseEntity]?.connection?.auth?.type}' - using auth.options 'serviceAccountKeyFile' requires mandatory configuration entity.${baseEntity}.connection.auth.options.jwtPayload.scope/subject`)
               throw err
             }
             let gkey: Record<string, any> = this.config_entity[baseEntity]?.connection?.auth?.options?._gkey
@@ -234,7 +229,7 @@ export class HelperRest {
             tokenUrl = gkey.token_uri // https://oauth2.googleapis.com/token
             const privateKey = gkey.private_key
             const jwtPayload: jsonwebtoken.JwtPayload = {
-              sub: this.config_entity[baseEntity]?.connection?.auth?.options?.subject, // firstname.lastname@mycompany.com
+              sub: this.config_entity[baseEntity]?.connection?.auth?.options?.jwtPayload?.subject, // gmail sender mail-address: noreply@mycompany.com
               iss: gkey.client_email, // service account email/user
               aud: gkey.token_uri,
               iat: Math.floor(Date.now() / 1000) - 60, // issued at
@@ -242,7 +237,7 @@ export class HelperRest {
             }
             jwtClaims = {
               ...jwtPayload,
-              scope: this.config_entity[baseEntity]?.connection?.auth?.options?.scope, // https://www.googleapis.com/auth/gmail.send
+              scope: this.config_entity[baseEntity]?.connection?.auth?.options?.jwtPayload?.scope, // https://www.googleapis.com/auth/gmail.send
             }
             jwtOpts = {
               algorithm: 'RS256',
@@ -257,23 +252,23 @@ export class HelperRest {
               assertion: jsonwebtoken.sign(jwtClaims, privateKey, jwtOpts),
             }
           } else {
-            // standard JWT - requires all configuation: tokenUrl, rawJwtPayload and certificate.key
+            // standard JWT - requires all configuation: tokenUrl, jwtPayload and tls.key
             if (!this.config_entity[baseEntity]?.connection?.auth?.options?.tokenUrl
-              || !this.config_entity[baseEntity]?.connection?.auth?.options?.rawJwtPayload
-              || typeof this.config_entity[baseEntity]?.connection?.auth?.options?.rawJwtPayload !== 'object') {
-              throw new Error(`auth.type '${this.config_entity[baseEntity]?.connection?.auth?.type}' (no tenantIdGUID/serviceAccountKeyFile using raw) - missing configuration entity.${baseEntity}.connection.auth.options.tokenUrl/rawJwtPayload`)
+              || !this.config_entity[baseEntity]?.connection?.auth?.options?.jwtPayload
+              || typeof this.config_entity[baseEntity]?.connection?.auth?.options?.jwtPayload !== 'object') {
+              throw new Error(`auth.type '${this.config_entity[baseEntity]?.connection?.auth?.type}' (no tenantIdGUID/serviceAccountKeyFile using raw) - missing configuration entity.${baseEntity}.connection.auth.options.tokenUrl/jwtPayload`)
             }
-            if (!this.config_entity[baseEntity]?.connection?.auth?.options?.certificate?.key) {
-              throw new Error(`auth type '${this.config_entity[baseEntity]?.connection?.auth?.type}' (no tenantIdGUID/serviceAccountKeyFile using raw) - missing options.certificate.key configuration`)
+            if (!this.config_entity[baseEntity]?.connection?.auth?.options?.tls?.key) {
+              throw new Error(`auth type '${this.config_entity[baseEntity]?.connection?.auth?.type}' (no tenantIdGUID/serviceAccountKeyFile using raw) - missing options.tls.key configuration`)
             }
             tokenUrl = this.config_entity[baseEntity].connection.auth.options.tokenUrl
-            let privateKey = this.config_entity[baseEntity]?.connection?.auth?.options?.certificate?._key || ''
+            let privateKey = this.config_entity[baseEntity]?.connection?.auth?.options?.tls?._key || ''
             if (!privateKey) {
-              privateKey = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.certificate.key, 'utf-8') || ''
-              if (privateKey) this.config_entity[baseEntity].connection.auth.options.certificate._key = privateKey
+              privateKey = fs.readFileSync(this.config_entity[baseEntity].connection.auth.options.tls.key, 'utf-8') || ''
+              if (privateKey) this.config_entity[baseEntity].connection.auth.options.tls._key = privateKey
             }
 
-            let jwtPayload = this.config_entity[baseEntity].connection.auth.options.rawJwtPayload
+            let jwtPayload = this.config_entity[baseEntity].connection.auth.options.jwtPayload
             if (!jwtPayload.iat) jwtPayload.iat = Math.floor(Date.now() / 1000) - 60
             if (!jwtPayload.exp) jwtPayload.exp = Math.floor(Date.now() / 1000) + 3600
 
@@ -419,6 +414,18 @@ export class HelperRest {
           org = utils.extendObj(org, opt.connection)
         }
 
+        // may use configuration type='oauth' and auto corrected to 'oauthJwtBearer'
+        if (this.config_entity[baseEntity]?.connection?.auth?.type == 'oauth') {
+          if (this.config_entity[baseEntity].connection.auth?.options?.tenantIdGUID) {
+            if (this.config_entity[baseEntity].connection.auth.options?.tls?.cert
+              && this.config_entity[baseEntity].connection.auth.options?.tls?.key
+              && this.config_entity[baseEntity].connection.auth.options.clientId
+            ) this.config_entity[baseEntity].connection.auth.type = 'oauthJwtBearer'
+          } else if (this.config_entity[baseEntity]?.connection?.auth?.options?.serviceAccountKeyFile) {
+            this.config_entity[baseEntity].connection.auth.type = 'oauthJwtBearer'
+          }
+        }
+
         switch (this.config_entity[baseEntity]?.connection?.auth?.type) {
           case 'basic':
             if (!this.config_entity[baseEntity]?.connection?.auth?.options?.username || !this.config_entity[baseEntity]?.connection?.auth?.options?.password) {
@@ -451,9 +458,9 @@ export class HelperRest {
             param.options.headers['Authorization'] = 'Bearer ' + Buffer.from(this.config_entity[baseEntity].connection.auth.options.token).toString('base64')
             break
           case 'oauthSamlBearer':
-            if (!this.config_entity[baseEntity]?.connection?.auth?.options?.clientId || !this.config_entity[baseEntity]?.connection?.auth?.options?.companyId
-              || !this.config_entity[baseEntity]?.connection?.auth?.options?.certificate?.key) {
-              const err = new Error(`auth.type 'oauthSamlBearer' - missing configuration entity.${baseEntity}.connection.auth.options...`)
+            if (!this.config_entity[baseEntity]?.connection?.auth?.options?.samlPayload?.clientId || !this.config_entity[baseEntity]?.connection?.auth?.options?.samlPayload?.companyId
+              || !this.config_entity[baseEntity]?.connection?.auth?.options?.tls?.key) {
+              const err = new Error(`auth.type 'oauthSamlBearer' - missing configuration entity.${baseEntity}.connection.auth.options.tls and/or options.samlPayload.clientId/companyId`)
               throw err
             }
             param.accessToken = await this.getAccessToken(baseEntity, ctx)
@@ -462,7 +469,7 @@ export class HelperRest {
           case 'oauthJwtBearer':
             // auth.options.tenantIdGUID => Microsoft Entra ID
             // auth.options.serviceAccountKeyFile => Google Service Account
-            // also support custom using tokenUrl/rawJwtPayload
+            // also support custom using tokenUrl/jwtPayload
             param.accessToken = await this.getAccessToken(baseEntity, ctx)
             param.options.headers['Authorization'] = `Bearer ${param.accessToken.access_token}`
             break
@@ -764,7 +771,7 @@ export class HelperRest {
   * ```
   * type defines authentication being used  
   * if type not defined, no authentication used  
-  * valid type is: `basic`, `oauth`, `token`, `bearer` or `oauthSamlBearer`  
+  * valid type is: `basic`, `oauth`, `token`, `bearer`, `oauthSamlBearer` or `oauthJwtBearer`  
   * 
   * for each valid type there are different auth.options  
   * 
@@ -815,10 +822,16 @@ export class HelperRest {
   * {
   *   "options": {
   *     "tokenUrl": "<tokenUrl>",
-  *     "clientId": "<clientId>",
-  *     "companyId": "<companyId>",
-  *     "userId": "<userId>",
-  *     "certificate": {
+  *     "samlPayload": {
+  *       "clientId": "<clientId>",
+  *       "companyId": "<companyId>",
+  *       "nameId": "<nameId>",
+  *       "lifetime": "<optional>"
+  *       "issuer": "<optional>",
+  *       "userIdentifierFormat": "<optional>",
+  *       "audience": "<optional>"
+  *     },
+  *     "tls": {
   *       "key": "<key-file-name>", // location: config/certs
   *       "cert": "<cert-file-name>", // location: config/certs
   *     }
@@ -833,7 +846,7 @@ export class HelperRest {
   *   "options": {
   *     "tenantIdGUID": "<Entra ID tenantIdGUID", // Entra ID authentication, if baseUrls not defined, baseUrls automatically set to [https://graph.microsoft.com/beta]
   *     "clientId": "<clientId>",
-  *     "certificate": { // files located in ./config/certs
+  *     "tls": { // files located in ./config/certs
   *       "key": "key.pem",
   *       "cert": "cert.pem"
   *     }
@@ -853,10 +866,10 @@ export class HelperRest {
   * {
   *   "options": {
   *     "tokenUrl":  "<tokenUrl",
-  *     "certificate": {
+  *     "tls": {
   *       "key": "<signing-key-file-name>" // key.pem file located in ./config/certs
   *      },
-  *     "rawJwtPayload": {
+  *     "jwtPayload": {
   *       "sub": "<subject>",
   *       "iss": "<issuer>",
   *       "aud": "<audience>",

package/lib/scimgateway.ts

@@ -2538,12 +2538,12 @@ export class ScimGateway {
         isMailLock = false
       }, (this.config.scimgateway.email.emailOnError.sendInterval || 15) * 1000 * 60)
 
-      const msgHtml = `<html><body><pre style="font-family: monospace; white-space: pre-wrap;">${msg}</pre><br/><p><strong>This is an automatically generated email - please do NOT reply to this email or forward to others</strong></p></body></html>`
+      const msgHtml = `<html><body><pre style="font-family: monospace; white-space: pre-wrap;">${msg}</pre><br/><p><strong>This is an automatically generated email - please do NOT reply to this email</strong></p></body></html>`
       const msgObj = {
         from: this.config.scimgateway.email.emailOnError.from,
         to: this.config.scimgateway.email.emailOnError.to,
         cc: this.config.scimgateway.email.emailOnError.cc,
-        subject: this.config.scimgateway.email.emailOnError.subject ? this.config.scimgateway.email.emailOnError.subject : 'SCIM Gateway error message',
+        subject: this.config.scimgateway.email.emailOnError.subject || 'SCIM Gateway error message',
         content: msgHtml,
       }
       this.sendMail(msgObj, true)
@@ -2870,9 +2870,7 @@ export class ScimGateway {
 
         const path = `/users/${msgObj.from}/sendMail`
         try {
-          if (this.config.scimgateway.email.auth?.options?.certificate?.key && this.config.scimgateway.email.auth?.options?.certificate?.cert) {
-            await this.helperRest.doRequest('undefined', 'POST', path, emailMessage, null, { connection: { auth: { type: 'oauthJwtBearer' } } })
-          } else await this.helperRest.doRequest('undefined', 'POST', path, emailMessage)
+          await this.helperRest.doRequest('undefined', 'POST', path, emailMessage)
           logger.debug(`${gwName}[${pluginName}] sendMail subject '${msgObj.subject}' sent to: ${msgObj.to}${(msgObj.cc) ? ',' + msgObj.cc : ''}`)
         } catch (err: any) {
           logger.error(`${gwName}[${pluginName}] sendMail subject '${msgObj.subject}' sending failed: ${err.message}`)
@@ -2894,7 +2892,7 @@ Content-Transfer-Encoding: quoted-printable
         const emailMessage = { raw: encodedMessage }
         const path = `/gmail/v1/users/${msgObj.from}/messages/send`
         try { // using opt connection argument type=oauthJwtBearer and options scope/subject because we want to keep simplified email.auth.type=oauth and options serviceAccountKeyFile
-          await this.helperRest.doRequest('undefined', 'POST', path, emailMessage, null, { connection: { auth: { type: 'oauthJwtBearer', options: { scope: 'https://www.googleapis.com/auth/gmail.send', subject: msgObj.from } } } })
+          await this.helperRest.doRequest('undefined', 'POST', path, emailMessage, null, { connection: { auth: { type: 'oauthJwtBearer', options: { jwtPayload: { scope: 'https://www.googleapis.com/auth/gmail.send', subject: msgObj.from } } } } })
           logger.debug(`${gwName}[${pluginName}] sendMail subject '${msgObj.subject}' sent to: ${msgObj.to}${(msgObj.cc) ? ',' + msgObj.cc : ''}`)
         } catch (err: any) {
           logger.error(`${gwName}[${pluginName}] sendMail subject '${msgObj.subject}' sending failed: ${err.message}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scimgateway",
-  "version": "5.1.5",
+  "version": "5.1.6",
   "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)",