scimgateway 5.0.14 → 5.0.15

package/README.md

@@ -16,7 +16,7 @@ Validated through IdP's:
 
 Latest news:  
 
-- Email, onError and sendMail() supports modern REST OAuth for Microsoft Exchange Online (ExO) and Google Workspace Gmail, alongside traditional SMTP Auth for all mail systems. HelperRest supports a wide range of common authentication methods, including basicAuth, bearerAuth, tokenAuth, oauth, oauthSamlAssertion, oauthJwtAssertion and Auth PassTrough 
+- Email, onError and sendMail() supports more secure RESTful OAuth for Microsoft Exchange Online (ExO) and Google Workspace Gmail, alongside traditional SMTP Auth for all mail systems. HelperRest supports a wide range of common authentication methods, including basicAuth, bearerAuth, tokenAuth, oauth, oauthSamlBearer, oauthJwtBearer and Auth PassTrough 
 - Major version **v5.0.0** marks a shift to native TypeScript support and prioritizes [Bun](https://bun.sh/) over Node.js. This upgrade requires some modifications to existing plugins.  
 - **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 Gateway now offers enhanced functionality with support for message subscription and automated provisioning using SCIM Stream
 - Authentication PassThrough letting plugin pass authentication directly to endpoint for avoid maintaining secrets at the gateway. E.g., using Entra ID application OAuth
@@ -437,7 +437,7 @@ Definitions in `endpoint` object are customized according to our plugin code. Pl
           "2603:1056:2000::/48",
           "2603:1057:2::/48"
         ]
-- **email** - Contains configuration for sending email from plugin or automated error notifications emailOnError. Note, for emailOnError only the first error will be sent until sendInterval have passed. Supporting both SMTP Auth and modern REST OAuth. For OAuth, currently Microsoft Exchange Online (ExO) and Google Workspace Gmail are supported
+- **email** - Sending email from plugin or automated error notifications emailOnError. For emailOnError only the first error will be sent until sendInterval have passed. Supporting both SMTP Auth and modern REST OAuth. For OAuth, currently Microsoft Exchange Online (ExO) and Google Workspace Gmail are supported - see configuration notes
 - **email.auth** - Authentication configuration
 - **email.auth.type** - `oauth` or `smtp`
 - **email.auth.options** - Authentication options - note, different options for type oauth and smtp
@@ -461,45 +461,6 @@ Definitions in `endpoint` object are customized according to our plugin code. Pl
 - **email.emailOnError.cc** - Optional comma separated list of cc mail addresses
 - **email.emailOnError.subject** - Optional mail subject, default `SCIM Gateway error message`
 
-	**Configuration notes for 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"
-
-	**Configuration notes for 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 `serviceAccountKeyFile` 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.onerror.from` mail address must have Google Workspace Business license
-
 - **stream** - See [SCIM Stream](https://elshaug.xyz/docs/scim-stream) for configuration details
 
 - **endpoint** - Contains endpoint specific configuration according to customized **plugin code**. 
@@ -561,6 +522,45 @@ Definitions in `endpoint` object are customized according to our plugin code. Pl
 		}  
 
 
+- 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
+
 
 ## Manual startup    
 
@@ -1009,17 +1009,17 @@ For JavaScript coding editor you may use [Visual Studio Code](https://code.visua
 
 Preparation:
 
-* Copy "best matching" example plugin e.g. `lib\plugin-mssql.ts` and `config\plugin-mssql.json` and rename both copies to your plugin name prefix e.g. plugin-mine.ts and plugin-mine.json (for SOAP Webservice endpoint we might use plugin-soap as a template) 
+* Copy "best matching" example plugin e.g. `lib\plugin-mssql.ts` and `config\plugin-mssql.json` and rename both copies to your plugin name prefix e.g. plugin-mine.ts and plugin-mine.json 
 * Edit plugin-mine.json and define a unique port number for the gateway setting  
 * Edit index.ts and include your plugin in the startup e.g. `const plugins = ['mine']');`  
-* Start SCIM Gateway and verify. If using CA Provisioning you could setup a SCIM endpoint using the port number you defined  
+* Start SCIM Gateway and verify using using your own SCIM API requests or your IdP/IGA system.  
 
 Now we are ready for custom coding by editing plugin-mine.ts
-Coding should be done step by step and each step should be verified and tested before starting the next (they are all highlighted by comments in existing code).  
+Coding should be done step by step and each step should be verified and tested before starting the next 
 
-1. **Turn off group functionality** - getGroups to return empty response  
+1. **Turn off group functionality** - getGroups to return empty response (gateway automatically use getGroups for some of the methods if groups not included)  
 Please see plugin-saphana that do not use groups.
-2. **getUsers** (test provisioning retrieve accounts)
+2. **getUsers** (test provisioning retrieve all accounts and single account)
 4. **createUser** (test provisioning new account)
 5. **deleteUser** (test provisioning delete account)
 6. **modifyUser** (test provisioning modify account)
@@ -1136,6 +1136,12 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 
 ## Change log  
 
+### v5.0.15
+
+[Improved]
+
+- HelperRest, auth.type=oauthSamlAssertion and auth.type=oauthJwtAssertion have been updated to `oauthSamlBearer` and `oauthJwtBearer` for consistency
+
 ### v5.0.14
 
 [Improved]

package/lib/helper-rest.ts

@@ -37,7 +37,7 @@ export class HelperRest {
           }
         } else if (this.config_entity[baseEntity]?.connection?.auth?.options?.serviceAccountKeyFile) { // Google, setting baseUrls to googleapis
           const type = this.config_entity[baseEntity]?.connection?.auth?.type
-          if (type === 'oauthJwtAssertion' || type === 'oauth') { // includes oauth because of email.auth.type
+          if (type === 'oauthJwtBearer' || type === 'oauth') { // includes oauth because of email.auth.type
             this.config_entity[baseEntity].connection.baseUrls = [this.googleUrl]
           }
         }
@@ -99,7 +99,7 @@ export class HelperRest {
         }
         break
 
-      case 'oauthSamlAssertion':
+      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()
@@ -123,7 +123,7 @@ export class HelperRest {
         }
         break
 
-      case 'oauthJwtAssertion':
+      case 'oauthJwtBearer':
         let privateKey = ''
         let jwtAttr: Record<string, any> = {}
         const serviceAccountKeyFile = this.config_entity[baseEntity]?.connection?.auth?.options?.serviceAccountKeyFile
@@ -284,7 +284,7 @@ export class HelperRest {
         }
 
         // Support  no auth, header based auth (e.g., config {"options":{"headers":{"APIkey":"123"}}}),
-        // basicAuth, bearerAuth, oauth, tokenAuth, oauthSamlAssertion, oauthJwtAssertion and auth PassTrough using request header authorization
+        // basicAuth, bearerAuth, oauth, tokenAuth, oauthSamlBearer, oauthJwtBearer and auth PassTrough using request header authorization
 
         let orgConnection: any
         if (opt?.connection) { // allow overriding/extending configuration connection by caller argument opt.connection
@@ -325,19 +325,19 @@ export class HelperRest {
             }
             param.options.headers['Authorization'] = 'Bearer ' + Buffer.from(this.config_entity[baseEntity].connection.auth.options.token).toString('base64')
             break
-          case 'oauthSamlAssertion':
+          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 'oauthSamlAssertion' - missing configuration entity.${baseEntity}.connection.auth.options...`)
+              const err = new Error(`auth.type 'oauthSamlBearer' - missing configuration entity.${baseEntity}.connection.auth.options...`)
               throw err
             }
             param.accessToken = await this.getAccessToken(baseEntity, ctx)
             param.options.headers['Authorization'] = `Bearer ${param.accessToken.access_token}`
             break
-          case 'oauthJwtAssertion':
+          case 'oauthJwtBearer':
             if (this.config_entity[baseEntity]?.connection?.auth?.options?.serviceAccountKeyFile) { // Google Service Account
               if (!this.config_entity[baseEntity]?.connection?.auth?.options?.scope || !this.config_entity[baseEntity]?.connection?.auth?.options?.subject) {
-                const err = new Error(`auth.type 'oauthJwtAssertion' - using auth.options 'serviceAccountKeyFile' also requires mandatory configuration entity.${baseEntity}.connection.auth.options.scope/subject`)
+                const err = new Error(`auth.type 'oauthJwtBearer' - using auth.options 'serviceAccountKeyFile' also requires mandatory configuration entity.${baseEntity}.connection.auth.options.scope/subject`)
                 throw err
               }
             } else if (!this.config_entity[baseEntity]?.connection?.auth?.options?.tokenUrl
@@ -347,7 +347,7 @@ export class HelperRest {
               || !this.config_entity[baseEntity]?.connection?.auth?.options?.audience
               || !this.config_entity[baseEntity]?.connection?.auth?.options?.certificate?.key
             ) {
-              const err = new Error(`auth.type 'oauthJwtAssertion' - when not using auth.options 'serviceAccountKeyFile' which is related to Google, following auth.options is mandatory: tokenUrl, scope, subject, issuer, audience, certificate.key`)
+              const err = new Error(`auth.type 'oauthJwtBearer' - when not using auth.options 'serviceAccountKeyFile' which is related to Google, following auth.options is mandatory: tokenUrl, scope, subject, issuer, audience, certificate.key`)
               throw err
             }
 
@@ -653,7 +653,7 @@ export class HelperRest {
   * ```
   * type defines authentication being used  
   * if type not defined, no authentication used  
-  * valid type is: `basic`, `oauth`, `token`, `bearer` or `oauthSamlAssertion`  
+  * valid type is: `basic`, `oauth`, `token`, `bearer` or `oauthSamlBearer`  
   * 
   * for each valid type there are different auth.options  
   * 
@@ -699,7 +699,7 @@ export class HelperRest {
   * }
   * ```
   * 
-  * type=**"oauthSamlAssertion"** having auth.options:
+  * type=**"oauthSamlBearer"** having auth.options:
   * ```
   * {
   *   "options": {
@@ -715,7 +715,7 @@ export class HelperRest {
   * }
   * ```
   * 
-  * type=**"oauthJwtAssertion"** having auth.options:
+  * type=**"oauthJwtBearer"** having auth.options:
   * ```
   * // Google API - baseUrls automatically set to [https://www.googleapis.com]
   * {

package/lib/logger.ts

@@ -49,7 +49,7 @@ export class Log {
     )
   }
 
-  private maskSecret = winston.format((info) => {
+  private maskSecret = winston.format((info: any) => {
     // mask json secrets
     let rePattern = new RegExp(this.reJson, 'i')
     let msg: string = info.message

package/lib/scimgateway.ts

@@ -2949,6 +2949,9 @@ export class ScimGateway {
       isHtml = true
       msgObj.content = `<html><body><pre style="font-family: monospace; white-space: pre-wrap;">${msgObj.content}</pre></body></html>`
     }
+    if (!msgObj.to) msgObj.to = ''
+    if (!msgObj.cc) msgObj.cc = ''
+    if (!msgObj.subject) msgObj.subject = 'SCIM Gateway message'
 
     if (authType === 'oauth') {
       if (!this.helperRest) this.helperRest = new HelperRest(this, { entity: { undefined: { connection: this.config.scimgateway.email } } })
@@ -2956,7 +2959,7 @@ export class ScimGateway {
         // Microsoft Exchange Online (ExO) - using Graph API
         const emailMessage: Record<string, any> = {
           message: {
-            subject: msgObj.subject ? msgObj.subject : 'SCIM Gateway message',
+            subject: msgObj.subject,
             body: {
               content: msgObj.content,
               contentType: isHtml ? 'HTML' : 'Text',
@@ -2993,16 +2996,13 @@ export class ScimGateway {
         const path = `/users/${msgObj.from}/sendMail`
         try {
           await this.helperRest.doRequest('undefined', 'POST', path, emailMessage)
-          logger.debug(`${gwName}[${pluginName}] sendMail subject '${emailMessage.message.subject}' sent to: ${msgObj.to}${(msgObj.cc) ? ',' + msgObj.cc : ''}`)
+          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 '${emailMessage.message.subject}' sending failed: ${err.message}`)
+          logger.error(`${gwName}[${pluginName}] sendMail subject '${msgObj.subject}' sending failed: ${err.message}`)
         }
         return
       } else if (this.config.scimgateway.email.auth?.options?.serviceAccountKeyFile) {
         // Google Workspace Gmail
-        if (!msgObj.to) msgObj.to = ''
-        if (!msgObj.cc) msgObj.cc = ''
-
         let mimeMessage = `From: ${msgObj.from}
 To: ${msgObj.to}
 Cc: ${msgObj.cc}
@@ -3016,11 +3016,11 @@ Content-Transfer-Encoding: quoted-printable
         const encodedMessage = btoa(mimeMessage)
         const emailMessage = { raw: encodedMessage }
         const path = `/gmail/v1/users/${msgObj.from}/messages/send`
-        try { // using opt connection argument type=oauthJwtAssertion 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: 'oauthJwtAssertion', options: { scope: 'https://www.googleapis.com/auth/gmail.send', subject: msgObj.from } } } })
-          logger.debug(`${gwName}[${pluginName}] sendMail subject '${emailMessage}' sent to: ${msgObj.to}${(msgObj.cc) ? ',' + msgObj.cc : ''}`)
+        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 } } } })
+          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 '${emailMessage}' sending failed: ${err.message}`)
+          logger.error(`${gwName}[${pluginName}] sendMail subject '${msgObj.subject}' sending failed: ${err.message}`)
         }
         return
       }
@@ -3057,15 +3057,15 @@ Content-Transfer-Encoding: quoted-printable
       from: msgObj.from, // sender address
       to: msgObj.to, // list of receivers - comma separated
       cc: msgObj.cc,
-      subject: msgObj.subject ? msgObj.subject : 'SCIM Gateway message',
+      subject: msgObj.subject,
     }
 
     if (isHtml) mailOptions.html = msgObj.content
     else mailOptions.text = msgObj.content
 
     transporter.sendMail(mailOptions, function (err) {
-      if (err != null) logger.error(`${gwName}[${pluginName}] sendMail subject '${mailOptions.subject}' sending failed: ${err.message}`)
-      else logger.debug(`${gwName}[${pluginName}] sendMail subject '${mailOptions.subject}' sent to: ${msgObj.to}${(msgObj.cc) ? ',' + msgObj.cc : ''}`)
+      if (err != null) logger.error(`${gwName}[${pluginName}] sendMail subject '${msgObj.subject}' sending failed: ${err.message}`)
+      else logger.debug(`${gwName}[${pluginName}] sendMail subject '${msgObj.subject}' sent to: ${msgObj.to}${(msgObj.cc) ? ',' + msgObj.cc : ''}`)
     })
   }
 

package/package.json

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