scimgateway 5.0.8 → 5.0.9

package/README.md

@@ -1111,6 +1111,12 @@ MIT © [Jarle Elshaug](https://www.elshaug.xyz)
 
 ## Change log  
 
+### v5.0.9
+
+[Improved]
+
+- HelperRest doRequest() now support configuration auth type `oauthSamlAssertion` for OAuth SAML token assertion. Please see code editor method IntelliSense for details
+
 ### v5.0.8
 
 [Fixed]

package/lib/helper-rest.ts

@@ -1,13 +1,13 @@
 import { HttpsProxyAgent } from 'https-proxy-agent'
 import { URL } from 'url'
 import { Buffer } from 'node:buffer'
+import { samlAssertion } from './samlAssertion.ts' // prereq: saml
 import fs from 'node:fs'
 import querystring from 'querystring'
 import * as utils from './utils.ts'
-// import type { ScimGateway } from 'scimgateway' // comment out for supporting Node.js, using type any and no IntelliSense
 
 /**
- * HelperRest includes function doRequest() for doing REST calls
+ * HelperRest includes function doRequest() for executing REST calls
  */
 export class HelperRest {
   private lock = new utils.Lock()
@@ -118,6 +118,31 @@ export class HelperRest {
         }
         break
 
+      case 'oauthSamlAssertion':
+        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 tokenEndpoint = tokenUrl
+        const audience = `scimgateway/${this.scimgateway.pluginName}`
+        const delay = 1
+
+        const assertion = await samlAssertion.run(context, cert, key, issuer, lifetime, clientId, nameId, userIdentifierFormat, tokenEndpoint, audience, delay)
+        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,
+          assertion: assertion,
+        }
+        break
+
       default:
         this.lock.release()
         throw new Error(`getAccessToken() none supported entity.${baseEntity}.connection.auth.type: '${this.config_entity[baseEntity]?.connection?.auth?.type}'`)
@@ -176,7 +201,7 @@ export class HelperRest {
    * @param baseEntity baseEntity
    * @param method GET/PATCH/PUT/DELETE
    * @param path e.g., /Users having baseUrl from configuration added, or full url e.g. https://mycompany.com/Users
-   * @param opt optional, connection optios
+   * @param opt optional, connection options
    * @param ctx optional, ctx included if using Auth PassThrough
    * @returns client.options needed for connect
    */
@@ -255,7 +280,7 @@ export class HelperRest {
                 const err = new Error(`auth type 'oauth' - missing configuration entity.${baseEntity}.connection.auth.options.clientId/clientSecret`)
                 throw err
               }
-              param.accessToken = await this.getAccessToken(baseEntity, ctx) // support Auth PassThrough
+              param.accessToken = await this.getAccessToken(baseEntity, ctx)
               param.options.headers['Authorization'] = `Bearer ${param.accessToken.access_token}`
               break
             case 'token':
@@ -263,7 +288,7 @@ export class HelperRest {
                 const err = new Error(`missing configuration entity.${baseEntity}.connection.auth.options.tokenUrl/password`)
                 throw err
               }
-              param.accessToken = await this.getAccessToken(baseEntity, ctx) // support Auth PassThrough
+              param.accessToken = await this.getAccessToken(baseEntity, ctx)
               param.options.headers['Authorization'] = `Bearer ${param.accessToken.access_token}`
               break
             case 'bearer':
@@ -273,6 +298,15 @@ export class HelperRest {
               }
               param.options.headers['Authorization'] = 'Bearer ' + Buffer.from(this.config_entity[baseEntity].connection.auth.options.token).toString('base64')
               break
+            case 'oauthSamlAssertion':
+              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...`)
+                throw err
+              }
+              param.accessToken = await this.getAccessToken(baseEntity, ctx)
+              param.options.headers['Authorization'] = `Bearer ${param.accessToken.access_token}`
+              break
             default:
             // no auth
           }
@@ -426,6 +460,7 @@ export class HelperRest {
       const timeout = setTimeout(() => controller.abort(), options.abortTimeout ? options.abortTimeout * 1000 : this.idleTimeout * 1000) // 120 seconds default abort timeout
       options.signal = signal
       const url = `${options.protocol}//${options.host}${options.port ? ':' + options.port : ''}${options.path}`
+      if (path.includes(')?$') && !options.headers['Accept-Encoding']) options.headers['Accept-Encoding'] = 'identity' // workaround for bun fetch error: "Decompression error: ShortRead" - have seen this error using OData with "<some-path>('xxx')?$expand=" or "<some-path>('xxx')?$select=" ref: https://github.com/oven-sh/bun/issues/8017
       // execute request
       const f = await fetch(url, options)
       clearTimeout(timeout)
@@ -534,15 +569,20 @@ export class HelperRest {
   *     "entity": {
   *       "undefined": {
   *         "connection": {
-  *           "baseUrls": [
+  *           "baseUrls": [  // ignored when using option tenantIdGUID
   *             "<baseUrl>", // "https://host1.company.com:8880",
   *             "<baseUrl2>" // optional using several baseUrls for failover
   *           ],
   *          "auth": {
-  *            "type": "<type>"",
+  *            "type": "<type>",
   *            "options": { <auth.options> }
   *           },
   *           "options": { <connection.options> }
+  *           "proxy": {
+  *             "host": "<host>", // http://proxy-host:1234
+  *             "username": "<username>", // username if authentication is required
+  *             "password": "<password>" // password if authentication is required
+  *           }
   *         }
   *       }
   *     }
@@ -551,11 +591,11 @@ export class HelperRest {
   * ```
   * type defines authentication being used  
   * if type not defined, no authentication used  
-  * valid type is: `basic`, `oauth`, `token` or `bearer`   
+  * valid type is: `basic`, `oauth`, `token`, `bearer` or `oauthSamlAssertion`  
   * 
   * for each valid type there are different auth.options  
   * 
-  * type=**basic**, auth.options:
+  * type=**"basic"** having auth.options:
   * ```
   * {
   *   "options": {
@@ -565,11 +605,11 @@ export class HelperRest {
   * }
   * ```
   * 
-  * type=**oauth**, auth.options:
+  * type=**"oauth"** having auth.options:
   * ```
   * {
   *   "options": {
-  *     "tenantIdGUID": "<Entra ID tenantIdGUID", // only defined when using Entra ID
+  *     "tenantIdGUID": "<Entra ID tenantIdGUID", // simplified configuration for using Microsoft Graph API
   *     "tokenUrl": "<tokenUrl>", // not used when tenantIdGUID defined
   *     "clientId": "<clientId",
   *     "clientSecret": "<clientSecret>"
@@ -577,7 +617,7 @@ export class HelperRest {
   * }
   * ```
   * 
-  * type=**token**, auth.options:
+  * type=**"token"** having auth.options:
   * ```
   * {
   *   "options": {
@@ -588,7 +628,7 @@ export class HelperRest {
   * }
   * ```
   * 
-  * type=**bearer**, auth.options:
+  * type=**"bearer"** having auth.options:
   * ```
   * {
   *   "options": {
@@ -597,6 +637,22 @@ export class HelperRest {
   * }
   * ```
   * 
+  * type=**"oauthSamlAssertion"** having auth.options:
+  * ```
+  * {
+  *   "options": {
+  *     "tokenUrl": "<tokenUrl>",
+  *     "clientId": "<clientId>",
+  *     "companyId": "<companyId>",
+  *     "userId": "<userId>",
+  *     "certificate": {
+  *       "key": "<key-file-name>", // location: config/certs
+  *       "cert": "<cert-file-name>", // location: config/certs
+  *     }
+  *   }
+  * }
+  * ```
+  * 
   * **connection.options** can be set according to web-standard fetch client options  
   * examples:  
   * ```

package/lib/logger.ts

@@ -96,7 +96,7 @@ export class Log {
       customMaskXml = customMasking.join('"?|')
       customMaskXml = '|' + customMaskXml + '"?'
     }
-    this.reJson = `^.*"(password|access_token|client_secret${customMaskJson})" ?: ?"([^"]+)".*`
+    this.reJson = `^.*"(password|access_token|client_secret|assertion${customMaskJson})" ?: ?"([^"]+)".*`
     this.reXml = `^.*(credentials"?|PasswordText"?|PasswordDigest"?|password"?${customMaskXml})>([^<]+)</.*`
 
     const trans: any = [

package/lib/samlAssertion.ts

@@ -0,0 +1,220 @@
+//
+// Purpose: create SAML token assertion that can be used by OAuth token request having grant type saml2-bearer
+// Based on: https://github.com/edersouza38/insomnia-plugin-sfsf-samlassertion
+//
+// MIT License
+//
+// Copyright (c) 2023 edersouza38
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+
+// @ts-expect-error type declaration file not found
+import { Saml20 as saml } from 'saml'
+import crypto from 'node:crypto'
+
+export const samlAssertionUtils = {
+  formatPrivateKey: function (input: string) {
+    // Validate PEM keys:
+    const keyArmor = /-----(BEGIN |END )(.*?) KEY-----/g
+    let v: any = [...input.matchAll(keyArmor)]
+    if (v.length > 0) {
+      if (v.length !== 2 || v[0][2] !== v[1][2] || v[0][2] !== 'PRIVATE') {
+        throw new Error('Invalid PEM private key. Make sure that the armoring is consistent and the PEM key is from the type "PRIVATE".')
+      }
+      return input.replace(/\r?\n|\r/g, '')
+    }
+
+    // Verify whether key was generated directly in SFSF:
+    const d = Buffer.from(input, 'base64').toString('utf-8')
+    v = d.split('###')
+    if (v.length === 2) {
+      input = v[0]
+    }
+    return `-----BEGIN PRIVATE KEY-----${input}-----END PRIVATE KEY-----`
+  },
+
+  formatCertificate: function (input: string) {
+    // Validate PEM keys:
+    const keyArmor = /-----(BEGIN |END )(.*?)-----/g
+    let v: any = [...input.matchAll(keyArmor)]
+    if (v.length > 0) {
+      if (v.length !== 2 || v[0][2] !== v[1][2]) {
+        throw new Error('Invalid PEM certificate. Make sure that the armoring is consistent.')
+      }
+      return input.replace(/\r?\n|\r/g, '')
+    }
+
+    // Verify whether key was generated directly in SFSF:
+    const d = Buffer.from(input, 'base64').toString('utf-8')
+    v = d.split('###')
+    if (v.length === 2) {
+      input = v[0]
+    }
+    return `-----BEGIN CERTIFICATE-----${input}-----END CERTIFICATE-----`
+  },
+
+  delay: function (time: number) {
+    return new Promise(resolve => setTimeout(resolve, time))
+  },
+
+  userIdentifierFormat: {
+    userId: 'userId',
+    userName: 'userName',
+    eMail: 'e-Mail',
+  },
+}
+
+export const samlAssertion = {
+  name: 'samlAssertionSFSF',
+  displayName: 'SAML Assertion - SFSF',
+  description: 'Create a SAML Assertion for SFSF OAuth2SAMLAssertion flow.',
+  args: [
+    {
+      displayName: 'X.509 Certificate',
+      description: 'X.509 Certificate used to identify the SAML IdP',
+      type: 'string',
+      placeholder: '-----BEGIN CERTIFICATE-----',
+    },
+    {
+      displayName: 'Private Key',
+      description: 'Private Key used to sign the SAML Assertion',
+      type: 'string',
+      placeholder: '-----BEGIN PRIVATE KEY-----',
+    },
+    {
+      displayName: 'SAML Issuer',
+      description: 'Name of the IdP issuing the SAML Assertion',
+      type: 'string',
+      defaultValue: 'local.insomnia.com',
+    },
+    {
+      displayName: 'Lifetime in seconds',
+      description: 'Lifetime of the SAML Assertion in seconds',
+      type: 'number',
+      defaultValue: 600,
+    },
+    {
+      displayName: 'Client Id',
+      description: 'Registered Client Id in SFSF',
+      type: 'string',
+      placeholder: 'OWE1Yzg0NTMyOGJlY2M4NWRiZGFiMGE3MTI5MA',
+    },
+    {
+      displayName: 'User Identifier',
+      description: 'User Identifier',
+      type: 'string',
+      placeholder: 'Username',
+    },
+    {
+      displayName: 'User Identifier Format',
+      description: 'User Identifier Format',
+      type: 'enum',
+      placeholder: 'User Identifier Format',
+      defaultValue: samlAssertionUtils.userIdentifierFormat.userId,
+      options: [
+        {
+          displayName: 'User ID',
+          value: samlAssertionUtils.userIdentifierFormat.userId,
+        },
+        {
+          displayName: 'Username',
+          value: samlAssertionUtils.userIdentifierFormat.userName,
+        },
+        {
+          displayName: 'E-Mail',
+          value: samlAssertionUtils.userIdentifierFormat.eMail,
+        },
+      ],
+    },
+    {
+      displayName: 'OAuth Token Endpoint',
+      description: 'SFSF OAuth Token Endpoint',
+      type: 'string',
+      placeholder: 'Username',
+    },
+    {
+      displayName: 'Audience',
+      description: 'Audience of the SAML Assertion',
+      type: 'string',
+      defaultValue: 'www.successfactors.com',
+    },
+    {
+      displayName: 'Delay (Seconds)',
+      description: 'Useful when the request is reaching the endpoint before the "validNotBefore" date from SAML assertion.',
+      type: 'number',
+      defaultValue: 0,
+    },
+  ],
+
+  async run(
+    context: any,
+    cert: any,
+    key: any,
+    issuer: any,
+    lifetime: any,
+    clientId: any,
+    nameId: any,
+    userIdentifierFormat: any,
+    tokenEndpoint: any,
+    audience: any,
+    delay: any,
+  ) {
+    const samlAttributes: Record<string, any> = {
+      api_key: clientId,
+    }
+
+    let nameIdentifierFormat
+      = 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'
+
+    switch (userIdentifierFormat) {
+      case samlAssertionUtils.userIdentifierFormat.eMail:
+        nameIdentifierFormat
+          = 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress'
+        break
+      case samlAssertionUtils.userIdentifierFormat.userName:
+        samlAttributes.use_username = 'true'
+        break
+      default:
+        break
+    }
+    const options = {
+      cert: samlAssertionUtils.formatCertificate(cert),
+      key: samlAssertionUtils.formatPrivateKey(key),
+      issuer: issuer,
+      lifetimeInSeconds: lifetime,
+      audiences: audience,
+      attributes: samlAttributes,
+      nameIdentifier: nameId,
+      nameIdentifierFormat: nameIdentifierFormat,
+      recipient: tokenEndpoint,
+      sessionIndex: '_' + crypto.randomUUID(),
+    }
+
+    const assertionBuff = Buffer.from(saml.create(options))
+    const assertion = assertionBuff.toString('base64')
+
+    if (delay > 0) {
+      await samlAssertionUtils.delay(delay * 1000)
+    }
+    return assertion
+  },
+}
+
+export default samlAssertion

package/lib/scimgateway.ts

@@ -2382,9 +2382,9 @@ export class ScimGateway {
             controller.close()
           },
         })
-        response = new Response(body ? stream : undefined, { status: ctx.response.status, headers: ctx.response.headers })
+        response = new Response(body ? stream : body, { status: ctx.response.status, headers: ctx.response.headers })
       } else {
-        response = new Response(body ? body : undefined, { status: ctx.response.status, headers: ctx.response.headers })
+        response = new Response(body, { status: ctx.response.status, headers: ctx.response.headers })
       }
       logResult(ctx)
       return response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scimgateway",
-  "version": "5.0.8",
+  "version": "5.0.9",
   "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)",
@@ -52,6 +52,7 @@
     "nodemailer": "^6.9.13",
     "passport": "^0.7.0",
     "passport-azure-ad": "^4.3.5",
+    "saml": "^3.0.1",
     "winston": "^3.13.0"
   },
   "peerDependencies": {