scimgateway/lib/plugin-ldap.ts

Using SCIM protocol as a gateway for user provisioning to other endpoints

// =================================================================================
// File:    plugin-ldap.js
//
// Author:  Jarle Elshaug
//
// Purpose: General ldap plugin having plugin-ldap.json configured for Active Directory.
//          Using endpointMapper for attribute flexibility. Includes some special logic
//          for Active Directory attributes like userAccountControl, unicodePW
//          and objectSid/objectGUID. objectSid/objectGUID can be used in mapper configuration.
//          e.g: replacing config.map.user.dn and config.map.group.dn with
//          config.map.user.objectSid or config.map.user.objectGUID e.g:
//
//          "objectSid": {
//            "mapTo": "id",
//            "type": "string"
//           },
//           "objectGUID": {
//             "mapTo": "userName",
//             "type": "string"
//            },
//            "userPrincipalName": {
//              "mapTo": "externalId",
//              "type": "string"
//             }
//
// Additional user/group filtering for restricting scope may be configured in endpoint.entity.xxx.ldap e.g:
// {
//   ...
//   "userFilter": "(memberOf=CN=grp1,OU=Groups,DC=test,DC=com)(!(memberOf=CN=Domain Admins,CN=Users,DC=test,DC=com))",
//   "groupFilter": "(!(cn=grp2))",
//   ...
//  }
//
// Configuration isOpenLdap true/false decides whether or not OpenLDAP Foundation protocol should
// be used for national characters and special characters in DN.
// For Active Directory, default isOpenLdap=false should be used
//
// Configuration allowModifyDN=true allows DN being changed based on modified mapping or namingAttribute
//
// Note, using Bun version < 1.2.5 and ldaps/TLS, environment must be set before started e.g.:
//   export NODE_EXTRA_CA_CERTS=/package-path/config/certs/ca.pem
//   or
//   export NODE_TLS_REJECT_UNAUTHORIZED=0
//
//   Bun version >= 1.2.5 supports configuration
//         "tls": {
//           "ca": ca-file-name, // located in confg/certs
//           "rejectUnauthorized": true
//         }
// 
// Attributes according to map definition in the configuration file plugin-ldap.json:
//
// GlobalUser   Template                  Scim                                          Endpoint
// -----------------------------------------------------------------------------------------------
// User name    %AC%                      userName                                      sAMAccountName
//                                        id                                            dn
// Suspended     -                        active                                        userAccountControl
// Password     %P%                       password                                      unicodePwd
// First Name   %UF%                      name.givenName                                givenName
// Last Name    %UL%                      name.familyName                               sn
// Full Name    %UN%                      name.formatted                                name
// Job title    %UT%                      title                                         title
//                                        groups.value                                  memberOf
// Emails                                 emails.work.value                             mail
// Phones                                 phoneNumbers.home.value                       homePhone
//                                        phoneNumbers.work.value                       mobile
// Addresses                              addresses.work.postalCode                     postalCode
//                                        addresses.work.streetAddress                  streetAddress
//                                        addresses.work.locality                       l
//                                        addresses.work.region                         st
//                                        addresses.work.country                        co
// Entitlements (for general purposes)    entitlements.description.value                description
//                                        entitlements.lastLogonTimestamp.value         lastLogonTimestamp
//                                        entitlements.homeDirectory.value              homeDirectory
//                                        entitlements.homeDrive.value                  homeDrive
//                                        entitlements.telephoneNumber.value            telephoneNumber
//                                        entitlements.physicalDeliveryOfficeName.value physicalDeliveryOfficeName
// createUser override userBase           entitlements.userBase.value                   N/A
//
// Groups:
//                                        id                                            dn
//                                        displayName                                   cn
//                                        members.value                                 member
//
// =================================================================================

import ldap from 'ldapjs'
// @ts-expect-error missing type definitions
import { BerReader } from '@ldapjs/asn1'
import fs from 'node:fs'

// for supporting nodejs running scimgateway package directly, using dynamic import instead of: import { ScimGateway } from 'scimgateway'
// scimgateway also inclues HelperRest: import { ScimGateway, HelperRest } from 'scimgateway'

// 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

// =================================================
// getUsers
// =================================================
scimgateway.getUsers = async (baseEntity, getObj, attributes, ctx) => {
  //
  // "getObj" = { attribute: <>, operator: <>, value: <>, rawFilter: <>, startIndex: <>, count: <> }
  // rawFilter is always included when filtering
  // attribute, operator and value are included when requesting unique object or simpel filtering
  // See comments in the "mandatory if-else logic - start"
  //
  // "attributes" is array of attributes to be returned - if empty, all supported attributes should be returned
  // Should normally return all supported user attributes having id and userName as mandatory
  // id and userName are most often considered as "the same" having value = <UserID>
  // Note, the value of returned 'id' will be used as 'id' in modifyUser and deleteUser
  // scimgateway will automatically filter response according to the attributes list
  //
  const action = 'getUsers'
  scimgateway.logDebug(baseEntity, `handling ${action} getObj=${getObj ? JSON.stringify(getObj) : ''} attributes=${attributes}`)
  if (!config.entity[baseEntity]) throw new Error(`unsupported baseEntity: ${baseEntity}`)

  const result: any = {
    Resources: [],
    totalResults: null,
  }

  if (attributes.length < 1) {
    for (const key in config.map.user) { // attributes = 'id,userName,attributes=profileUrl,entitlements,x509Certificates.value,preferredLanguage,addresses,displayName,timezone,name.middleName,roles,locale,title,photos,meta.location,ims,phoneNumbers,emails,meta.version,name.givenName,name.honorificSuffix,name.honorificPrefix,name.formatted,nickName,meta.created,active,externalId,meta.lastModified,name.familyName,userType,groups.value'
      if (config.map.user[key].mapTo) attributes.push(config.map.user[key].mapTo)
    }
  }
  const [attrs] = scimgateway.endpointMapper('outbound', attributes, config.map.user) // SCIM/CustomSCIM => endpoint attribute naming

  const method = 'search'
  const scope = 'sub'
  let base = config.entity[baseEntity].ldap.userBase
  let ldapOptions

  const [userIdAttr, err] = scimgateway.endpointMapper('outbound', 'userName', config.map.user) // e.g. 'userName' => 'sAMAccountName'
  if (err) throw new Error(`${action} error: ${err.message}`)

  // start mandatory if-else logic
  if (getObj.operator) {
    if (getObj.operator === 'eq' && ['id', 'userName', 'externalId'].includes(getObj.attribute)) {
      // mandatory - unique filtering - single unique user to be returned - correspond to getUser() in versions < 4.x.x
      if (getObj.attribute === 'id') { // lookup using dn or objectSid/objectGUID (Active Directory)
        if (config.useSID_id) {
          const sid = convertStringToSid(getObj.value) // sid using formatted string instead of default hex
          if (!sid) throw new Error(`${action} error: ${getObj.attribute}=${getObj.value} - attribute having a none valid SID string`)
          base = `<SID=${sid}>`
        } else if (config.useGUID_id) {
          const guid = Buffer.from(getObj.value, 'base64').toString('hex')
          base = `<GUID=${guid}>` // '<GUID=b3975b675d3a21498b4e511e1a8ccb9e>'
        } else base = getObj.value
        ldapOptions = {
          attributes: attrs,
        }
      } else {
        const [userIdAttr, err] = scimgateway.endpointMapper('outbound', getObj.attribute, config.map.user) // e.g. 'userName' => 'sAMAccountName'
        if (err) throw new Error(`${action} error: ${err.message}`)
        if (userIdAttr === 'objectSid') {
          const sid = convertStringToSid(getObj.value)
          if (!sid) throw new Error(`${action} error: ${getObj.attribute}=${getObj.value} - attribute having a none valid SID string`)
          base = `<SID=${sid}>`
          ldapOptions = {
            attributes: attrs,
          }
        } else if (userIdAttr === 'objectGUID') {
          const guid = Buffer.from(getObj.value, 'base64').toString('hex')
          base = `<GUID=${guid}>`
          ldapOptions = {
            attributes: attrs,
          }
        } else { // search instead of lookup
          const filter = createAndFilter(baseEntity, 'user', [{ attribute: userIdAttr, value: getObj.value }])
          ldapOptions = {
            filter,
            scope: 'sub',
            attributes: attrs,
          }
        }
      }
    } else if (getObj.operator === 'eq' && getObj.attribute === 'group.value') {
      // optional - only used when groups are member of users, not default behavior - correspond to getGroupUsers() in versions < 4.x.x
      throw new Error(`${action} error: not supporting groups member of user filtering: ${getObj.rawFilter}`)
    } else {
      // optional - simpel filtering
      if (getObj.operator === 'eq') {
        const [filterAttr, err] = scimgateway.endpointMapper('outbound', getObj.attribute, config.map.user)
        if (err) throw new Error(`${action} error: ${err.message}`)
        const filter = createAndFilter(baseEntity, 'user', [{ attribute: filterAttr, value: getObj.value }])
        ldapOptions = {
          filter,
          scope,
          attributes: attrs,
        }
      } else {
        throw new Error(`${action} error: not supporting simpel filtering: ${getObj.rawFilter}`)
      }
    }
  } else if (getObj.rawFilter) {
    // optional - advanced filtering having and/or/not - use getObj.rawFilter
    throw new Error(`${action} error: not supporting advanced filtering: ${getObj.rawFilter}`)
  } else {
    // mandatory - no filtering (!getObj.operator && !getObj.rawFilter) - all users to be returned - correspond to exploreUsers() in versions < 4.x.x
    const filter = createAndFilter(baseEntity, 'user', [{ attribute: userIdAttr, value: '*' }])
    ldapOptions = {
      filter,
      scope,
      attributes: attrs,
    }
  }
  // end mandatory if-else logic

  if (!ldapOptions) throw new Error(`${action} error: mandatory if-else logic not fully implemented`)

  try {
    const users: any = await doRequest(baseEntity, method, base, ldapOptions, ctx) // ignoring SCIM paging startIndex/count - get all
    result.totalResults = users.length
    result.Resources = await Promise.all(users.map(async (user: any) => { // Promise.all because of async map
      // endpoint spesific attribute handling
      // "active" must be handled separate
      if (user.userAccountControl !== undefined) { // SCIM "active" - Active Directory
        const userAccountControl = user.userAccountControl// ACCOUNTDISABLE 0x0002
        if ((userAccountControl & 0x0002) === 0x0002) user.userAccountControl = false
        else user.userAccountControl = true
      }

      if (user.memberOf) {
        if (!config.map.group) user.memberOf = [] // empty any values
        if (config.useSID_id || config.useGUID_id) { // Active Directory - convert memberOf having dn values to objectSid/objectGUID
          const arr: string[] = []
          try {
            if (Array.isArray(user.memberOf)) {
              for (let i = 0; i < user.memberOf.length; i++) {
                const id = await dnToSidGuid(baseEntity, user.memberOf[i], ctx)
                if (!id) throw new Error(`dnToGuid did not return any objectGUID value for dn=${user.memberOf[i]}`)
                arr.push(id)
              }
              user.memberOf = arr
            } else {
              const id = await dnToSidGuid(baseEntity, user.memberOf, ctx)
              if (!id) throw new Error(`dnToGuid did not return any objectGUID value for dn=${user.memberOf}`)
              user.memberOf = [id]
            }
          } catch (err: any) {
            throw new Error(err.message)
          }
        }
      }

      const scimObj = scimgateway.endpointMapper('inbound', user, config.map.user)[0] // endpoint attribute naming => SCIM
      // if (!scimObj.groups) scimObj.groups = []
      return scimObj
    }))
  } catch (err: any) {
    throw new Error(`${action} error: ${err.message}`)
  }

  return result
}

// =================================================
// createUser
// =================================================
scimgateway.createUser = async (baseEntity, userObj, ctx) => {
  const action = 'createUser'
  scimgateway.logDebug(baseEntity, `handling ${action} userObj=${JSON.stringify(userObj)}`)

  let userBase = null
  if (userObj.entitlements && userObj.entitlements.userbase) { // override default userBase (type userbase will be lowercase)
    if (userObj.entitlements.userbase.value) {
      userBase = userObj.entitlements.userbase.value // temporary and not in config.map, will not be sent to endpoint
    }
  }
  if (!userBase) userBase = config.entity[baseEntity].ldap.userBase

  // convert SCIM attributes to endpoint attributes according to config.map
  const [endpointObj] = scimgateway.endpointMapper('outbound', userObj, config.map.user) // use [endpointObj, err] and if err, throw error to catch non supported attributes

  // endpoint spesific attribute handling
  if (endpointObj.sAMAccountName !== undefined) { // Active Directory
    const userAccountControl = 512 // NORMAL_ACCOUNT
    endpointObj.userAccountControl = userAccountControl ^ 0x0002 // disable user (will be enabled if password provided)
    if (!endpointObj.userPrincipalName) {
      if (endpointObj.mail) endpointObj.userPrincipalName = endpointObj.mail
      else endpointObj.userPrincipalName = endpointObj.sAMAccountName
    }
    userObj.userName = endpointObj.sAMAccountName // ensure user dn based on sAMAccountName
  }

  if (endpointObj.unicodePwd) { // Active Directory - SCIM "password"  - UTF16LE encoded password in quotes
    let pwd = ''
    const str = `"${endpointObj.unicodePwd}"`
    for (let i = 0; i < str.length; i++) {
      pwd += String.fromCharCode(str.charCodeAt(i) & 0xFF, (str.charCodeAt(i) >>> 8) & 0xFF)
    }
    endpointObj.unicodePwd = pwd
    const userAccountControl = 512 // NORMAL_ACCOUNT
    endpointObj.userAccountControl = userAccountControl & (~0x0002) // enable user
    endpointObj.pwdLastSet = 0 // user must change password on next logon
  }

  // endpointObj.objectClass is mandatory and must must match your ldap schema
  endpointObj.objectClass = config.entity[baseEntity].ldap.userObjectClasses // Active Directory: ["user", "person", "organizationalPerson", "top"]

  let base = ''
  const [userNamingAttr, scimAttr] = getNamingAttribute(baseEntity, 'user') // ['CN', 'userName']
  const arr = scimAttr.split('.')
  if (arr.length < 2) {
    base = `${userNamingAttr}=${userObj[scimAttr]},${userBase}`
  } else {
    base = `${userNamingAttr}=${userObj[arr[0]][arr[1]]},${userBase}`
  }

  const method = 'add'
  const ldapOptions = endpointObj

  try {
    await doRequest(baseEntity, method, base, ldapOptions, ctx)
    return null
  } catch (err: any) {
    const newErr = new Error(`${action} error: ${err.message}`)
    if (newErr.message.includes('ENTRY_EXISTS')) newErr.name += '#409' // customErrCode
    throw newErr
  }
}

// =================================================
// deleteUser
// =================================================
scimgateway.deleteUser = async (baseEntity, id, ctx) => {
  const action = 'deleteUser'
  scimgateway.logDebug(baseEntity, `handling ${action} id=${id}`)

  const method = 'del'
  let base
  if (config.useSID_id) {
    const sid = convertStringToSid(id)
    if (!sid) throw new Error(`${action} error: id=${id} - attribute having a none valid SID string`)
    base = `<SID=${sid}>`
  } else if (config.useGUID_id) {
    const guid = Buffer.from(id, 'base64').toString('hex')
    base = `<GUID=${guid}>`
  } else base = id // dn
  const ldapOptions = {}

  try {
    await doRequest(baseEntity, method, base, ldapOptions, ctx)
    return null
  } catch (err: any) {
    throw new Error(`${action} error: ${err.message}`)
  }
}

// =================================================
// modifyUser
// =================================================
scimgateway.modifyUser = async (baseEntity, id, attrObj, ctx) => {
  const action = 'modifyUser'
  scimgateway.logDebug(baseEntity, `handling ${action} id=${id} attrObj=${JSON.stringify(attrObj)}`)

  // groups must be handled separate - using group member of user and not user member of group
  if (attrObj.groups) { // not supported by AD - will fail (not allowing updating users memberOf attribute, must update group instead of user)
    const groups = attrObj.groups
    delete attrObj.groups // make sure to be removed from attrObj

    const [groupsAttr] = scimgateway.endpointMapper('outbound', 'groups.value', config.map.user)
    const grp: any = { add: {}, remove: {} }
    grp.add[groupsAttr] = []
    grp.remove[groupsAttr] = []

    for (let i = 0; i < groups.length; i++) {
      const el = groups[i]
      if (el.operation && el.operation === 'delete') { // delete from users group attribute
        grp.remove[groupsAttr].push(el.value)
      } else { // add to users group attribute
        grp.add[groupsAttr].push(el.value)
      }
    }

    const method = 'modify'
    let base
    if (config.useSID_id) {
      const sid = convertStringToSid(id)
      if (!sid) throw new Error(`${action} error: id=${id} - attribute having a none valid SID string`)
      base = `<SID=${sid}>`
    } else if (config.useGUID_id) {
      const guid = Buffer.from(id, 'base64').toString('hex')
      base = `<GUID=${guid}>`
    } else base = id // dn

    try {
      if (grp.add[groupsAttr].length > 0) {
        const ldapOptions = {
          operation: 'add',
          modification: grp.add,
        }
        await doRequest(baseEntity, method, base, ldapOptions, ctx)
      }
      if (grp.remove[groupsAttr].length > 0) {
        const ldapOptions = {
          operation: 'delete',
          modification: grp.remove,
        }
        await doRequest(baseEntity, method, base, ldapOptions, ctx)
      }
    } catch (err: any) {
      throw new Error(`${action} error: ${err.message}`)
    }
  }

  if (Object.keys(attrObj).length < 1) return null // only groups included

  // convert SCIM attributes to endpoint attributes according to config.map
  const [endpointObj] = scimgateway.endpointMapper('outbound', attrObj, config.map.user)

  // endpoint spesific attribute handling
  if (endpointObj.userAccountControl !== undefined) { // SCIM "active" - Active Directory
    // can't use getUser because there is "active" logic overriding original userAccountControl that we want
    // const usr = await scimgateway.getUser(baseEntity, { filter: 'id', identifier: id }, 'active', ctx)
    const activeAttr = 'userAccountControl'
    const method = 'search'
    let base
    if (config.useSID_id) {
      const sid = convertStringToSid(id)
      if (!sid) throw new Error(`${action} error: id=${id} - attribute having a none valid SID string`)
      base = `<SID=${sid}>`
    } else if (config.useGUID_id) {
      const guid = Buffer.from(id, 'base64').toString('hex')
      base = `<GUID=${guid}>`
    } else base = id // dn
    const ldapOptions: any = {
      attributes: activeAttr,
    }

    const users: any = await doRequest(baseEntity, method, base, ldapOptions, ctx)
    if (users.length === 0) throw new Error(`${action} error: ${id} not found`)
    else if (users.length > 1) throw new Error(`${action} error: ${ldapOptions.filter} returned more than one user for ${id}`)
    const usr = users[0]

    let userAccountControl
    if (usr.userAccountControl) userAccountControl = usr.userAccountControl // ACCOUNTDISABLE 0x0002
    else throw new Error(`${action} error: did not retrieve any value for attribute "${activeAttr}/active"`)
    if (attrObj.active === false) userAccountControl = userAccountControl ^ 0x0002 // disable user
    else userAccountControl = userAccountControl = userAccountControl & (~(0x0002 + 0x0010)) // enable user, also turn off any LOCKOUT 0x0010
    endpointObj.userAccountControl = userAccountControl // now converted from active (true/false) to userAccountControl
  }

  if (endpointObj.unicodePwd) { // SCIM "password" - Active Directory - UTF16LE encoded password in quotes
    let pwd = ''
    const str = `"${endpointObj.unicodePwd}"`
    for (let i = 0; i < str.length; i++) {
      pwd += String.fromCharCode(str.charCodeAt(i) & 0xFF, (str.charCodeAt(i) >>> 8) & 0xFF)
    }
    endpointObj.unicodePwd = pwd
  }

  const method = 'modify'
  let base
  if (config.useSID_id) {
    const sid = convertStringToSid(id)
    if (!sid) throw new Error(`${action} error: id=${id} - attribute having a none valid SID string`)
    base = `<SID=${sid}>`
  } else if (config.useGUID_id) {
    const guid = Buffer.from(id, 'base64').toString('hex')
    base = `<GUID=${guid}>`
  } else base = id // dn

  if (Object.keys(endpointObj).length < 1) return null
  const ldapOptions = {
    operation: 'replace',
    modification: endpointObj,
  }

  try {
    const newDN = checkIfNewDN(baseEntity, base, 'user', attrObj, endpointObj)
    await doRequest(baseEntity, method, base, ldapOptions, ctx)
    if (newDN && config.entity[baseEntity].ldap.allowModifyDN) {
      // modify DN
      await doRequest(baseEntity, 'modifyDN', base, { modification: { newDN } }, ctx)
      // clean up zoombie group members and use the new user DN incase not handled by ldap server
      const [memberAttr] = scimgateway.endpointMapper('outbound', 'members.value', config.map.group)
      if (memberAttr) {
        const grp: any = { add: {}, remove: {} }
        grp.add[memberAttr] = []
        grp.remove[memberAttr] = []
        let r
        try {
          const ob = { attribute: 'members.value', operator: 'eq', value: base } // base is old DN
          const attributes = ['id', 'displayName']
          r = await scimgateway.getGroups(baseEntity, ob, attributes, ctx)
        } catch (err) { } // ignore errors incase method not implemented
        if (r && r.Resources && Array.isArray(r.Resources) && r.Resources.length > 0) {
          for (let i = 0; i < r.Resources.length; i++) {
            if (!r.Resources[i].id) continue
            const grpId = decodeURIComponent(r.Resources[i].id)
            grp.remove[memberAttr] = [base]
            grp.add[memberAttr] = [newDN]
            await Promise.all([
              doRequest(baseEntity, method, grpId, { operation: 'add', modification: grp.add }, ctx),
              doRequest(baseEntity, method, grpId, { operation: 'delete', modification: grp.remove }, ctx),
            ])
          }
        }
        // return full user object to avoid scimgateway doing same getUser() using original id/dn that now will fail
        const getObj = { attribute: 'id', operator: 'eq', value: newDN }
        const res = await scimgateway.getUsers(baseEntity, getObj, [], ctx)
        return res
      }
    }
    return null
  } catch (err: any) {
    throw new Error(`${action} error: ${err.message}`)
  }
}

// =================================================
// getGroups
// =================================================
scimgateway.getGroups = async (baseEntity, getObj, attributes, ctx) => {
  //
  // "getObj" = { attribute: <>, operator: <>, value: <>, rawFilter: <>, startIndex: <>, count: <> }
  // rawFilter is always included when filtering
  // attribute, operator and value are included when requesting unique object or simpel filtering
  // See comments in the "mandatory if-else logic - start"
  //
  // "attributes" is array of attributes to be returned - if empty, all supported attributes should be returned
  // Should normally return all supported group attributes having id, displayName and members as mandatory
  // id and displayName are most often considered as "the same" having value = <GroupName>
  // Note, the value of returned 'id' will be used as 'id' in modifyGroup and deleteGroup
  // scimgateway will automatically filter response according to the attributes list
  //
  const action = 'getGroups'
  scimgateway.logDebug(baseEntity, `handling ${action} getObj=${getObj ? JSON.stringify(getObj) : ''} attributes=${attributes}`)
  if (!config.entity[baseEntity]) throw new Error(`unsupported baseEntity: ${baseEntity}`)

  const result: any = {
    Resources: [],
    totalResults: null,
  }

  if (!config?.map?.group || !config.entity[baseEntity]?.ldap?.groupBase) { // not using groups
    scimgateway.logDebug(baseEntity, `${action} skip group handling - missing configuration endpoint.map.group or groupBase`)
    return result
  }

  if (attributes.length < 1) {
    for (const key in config.map.group) {
      if (config.map.group[key].mapTo) {
        attributes.push(config.map.group[key].mapTo)
      }
    }
  }

  const [attrs] = scimgateway.endpointMapper('outbound', attributes, config.map.group) // SCIM/CustomSCIM => endpoint attribute naming
  const method = 'search'
  const scope = 'sub'
  let base = config.entity[baseEntity].ldap.groupBase
  let ldapOptions

  const [groupDisplayNameAttr, err1] = scimgateway.endpointMapper('outbound', 'displayName', config.map.group) // e.g. 'displayName' => 'cn'
  if (err1) throw new Error(`${action} error: ${err1.message}`)

  // mandatory if-else logic - start
  if (getObj.operator) {
    if (getObj.operator === 'eq' && ['id', 'displayName', 'externalId'].includes(getObj.attribute)) {
      // mandatory - unique filtering - single unique user to be returned - correspond to getUser() in versions < 4.x.x
      if (getObj.attribute === 'id') { // lookup using dn or objectSid/objectGUID (Active Directory)
        if (config.useSID_id) {
          const sid = convertStringToSid(getObj.value) // sid using formatted string instead of default hex
          if (!sid) throw new Error(`${action} error: ${getObj.attribute}=${getObj.value} - attribute having a none valid SID string`)
          base = `<SID=${sid}>`
        } else if (config.useGUID_id) {
          const guid = Buffer.from(getObj.value, 'base64').toString('hex')
          base = `<GUID=${guid}>`
        } else base = getObj.value
        ldapOptions = {
          attributes: attrs,
        }
      } else {
        const [groupIdAttr, err] = scimgateway.endpointMapper('outbound', getObj.attribute, config.map.group)
        if (err) throw new Error(`${action} error: ${err.message}`)
        if (groupIdAttr === 'objectSid') {
          const sid = convertStringToSid(getObj.value)
          if (!sid) throw new Error(`${action} error: ${getObj.attribute}=${getObj.value} - attribute having a none valid SID string`)
          base = `<SID=${sid}>`
          ldapOptions = {
            attributes: attrs,
          }
        } else if (groupIdAttr === 'objectGUID') {
          const guid = Buffer.from(getObj.value, 'base64').toString('hex')
          base = `<GUID=${guid}>`
          ldapOptions = {
            attributes: attrs,
          }
        } else { // search instead of lookup
          const filter = createAndFilter(baseEntity, 'group', [{ attribute: groupIdAttr, value: getObj.value }])
          ldapOptions = {
            filter,
            scope,
            attributes: attrs,
          }
        }
      }
    } else if (getObj.operator === 'eq' && getObj.attribute === 'members.value') {
      // mandatory - return all groups the user 'id' (getObj.value) is member of - correspond to getGroupMembers() in versions < 4.x.x
      // Resources = [{ id: <id-group>> , displayName: <displayName-group>, members [{value: <id-user>}] }]
      ldapOptions = 'getMemberOfGroups'
    } else {
      // optional - simpel filtering
      if (getObj.operator === 'eq') {
        const [filterAttr, err] = scimgateway.endpointMapper('outbound', getObj.attribute, config.map.group)
        if (err) throw new Error(`${action} error: ${err.message}`)
        const filter = createAndFilter(baseEntity, 'group', [{ attribute: filterAttr, value: getObj.value }])
        ldapOptions = {
          filter,
          scope,
          attributes: attrs,
        }
      } else {
        throw new Error(`${action} error: not supporting simpel filtering: ${getObj.rawFilter}`)
      }
    }
  } else if (getObj.rawFilter) {
    // optional - advanced filtering having and/or/not - use getObj.rawFilter
    throw new Error(`${action} error: not supporting advanced filtering: ${getObj.rawFilter}`)
  } else {
    // mandatory - no filtering (!getObj.operator && !getObj.rawFilter) - all groups to be returned - correspond to exploreGroups() in versions < 4.x.x
    const filter = createAndFilter(baseEntity, 'group', [{ attribute: groupDisplayNameAttr, value: '*' }])
    ldapOptions = {
      filter,
      scope,
      attributes: attrs,
    }
  }
  // mandatory if-else logic - end

  if (!ldapOptions) throw new Error(`${action} error: mandatory if-else logic not fully implemented`)

  try {
    if (ldapOptions === 'getMemberOfGroups') result.Resources = await getMemberOfGroups(baseEntity, getObj.value, ctx)
    else {
      const groups: any = await doRequest(baseEntity, method, base, ldapOptions, ctx)
      result.Resources = await Promise.all(groups.map(async (group: any) => { // Promise.all because of async map
        if (config.useSID_id || config.useGUID_id) {
          if (group.member) {
            const arr: string[] = []
            if (Array.isArray(group.member)) {
              for (let i = 0; i < group.member.length; i++) {
                const id = await dnToSidGuid(baseEntity, group.member[i], ctx)
                if (!id) throw new Error(`dnToSidGuid() did not return any ${config.useSID_id ? 'objectSid' : 'objectGUID'} value for dn=${group.member[i]}`)
                arr.push(id)
              }
              group.member = arr
            } else {
              const id = await dnToSidGuid(baseEntity, group.member, ctx)
              if (!id) throw new Error(`dnToSidGuid() did not return any ${config.useSID_id ? 'objectSid' : 'objectGUID'} value for ${group.member}`)
              group.member = [id]
            }
          }
        }
        return scimgateway.endpointMapper('inbound', group, config.map.group)[0] // endpoint attribute naming => SCIM
      }))
    }

    result.totalResults = result.Resources.length
    return result
  } catch (err: any) {
    throw new Error(`${action} error: ${err.message}`)
  }
}

// =================================================
// createGroup
// =================================================
scimgateway.createGroup = async (baseEntity, groupObj, ctx) => {
  const action = 'createGroup'
  scimgateway.logDebug(baseEntity, `handling ${action} groupObj=${JSON.stringify(groupObj)}`)

  if (!config.map.group) throw new Error(`${action} error: missing configuration endpoint.map.group`)
  const groupBase = config.entity[baseEntity].ldap.groupBase

  // convert SCIM attributes to endpoint attributes according to config.map
  const [endpointObj] = scimgateway.endpointMapper('outbound', groupObj, config.map.group)

  // endpointObj.objectClass is mandatory and must must match your ldap schema
  endpointObj.objectClass = config.entity[baseEntity].ldap.groupObjectClasses // Active Directory: ["group"]

  let base = ''
  const [groupNamingAttr, scimAttr] = getNamingAttribute(baseEntity, 'group') // ['CN', 'displayName']
  const arr = scimAttr.split('.')
  if (arr.length < 2) {
    base = `${groupNamingAttr}=${groupObj[scimAttr]},${groupBase}`
  } else {
    base = `${groupNamingAttr}=${groupObj[arr[0]][arr[1]]},${groupBase}`
  }

  const method = 'add'
  const ldapOptions = endpointObj

  try {
    await doRequest(baseEntity, method, base, ldapOptions, ctx)
    const res = await scimgateway.getGroups(baseEntity, { attribute: 'id', operator: 'eq', value: base }, [], ctx)
    if (res && Array.isArray(res.Resources) && res.Resources.length === 1) return res.Resources[0]
    else return null
  } catch (err: any) {
    const newErr = new Error(`${action} error: ${err.message}`)
    if (newErr.message.includes('ENTRY_EXISTS')) newErr.name += '#409' // customErrCode
    throw newErr
  }
}

// =================================================
// deleteGroup
// =================================================
scimgateway.deleteGroup = async (baseEntity, id, ctx) => {
  const action = 'deleteGroup'
  scimgateway.logDebug(baseEntity, `handling ${action} id=${id}`)

  if (!config.map.group) throw new Error(`${action} error: missing configuration endpoint.map.group`)
  const method = 'del'
  let base
  if (config.useSID_id) {
    const sid = convertStringToSid(id)
    if (!sid) throw new Error(`${action} error: id=${id} - attribute having a none valid SID string`)
    base = `<SID=${sid}>`
  } else if (config.useGUID_id) {
    const guid = Buffer.from(id, 'base64').toString('hex')
    base = `<GUID=${guid}>`
  } else base = id // dn
  const ldapOptions = {}

  try {
    await doRequest(baseEntity, method, base, ldapOptions, ctx)
    return null
  } catch (err: any) {
    throw new Error(`${action} error: ${err.message}`)
  }
}

// =================================================
// modifyGroup
// =================================================
scimgateway.modifyGroup = async (baseEntity, id, attrObj, ctx) => {
  const action = 'modifyGroup'
  scimgateway.logDebug(baseEntity, `handling ${action} id=${id} attrObj=${JSON.stringify(attrObj)}`)

  if (!config.map.group) throw new Error(`${action} error: missing configuration endpoint.map.group`)
  if (attrObj.members && !Array.isArray(attrObj.members)) {
    throw new Error(`${action} error: ${JSON.stringify(attrObj)} - correct syntax is { "members": [...] }`)
  }

  const [memberAttr] = scimgateway.endpointMapper('outbound', 'members.value', config.map.group)
  if (!memberAttr && attrObj.members) throw new Error(`${action} error: missing attribute mapping configuration for group members`)

  const grp: any = { add: {}, remove: {} }
  grp.add[memberAttr] = []
  grp.remove[memberAttr] = []

  for (let i = 0; i < attrObj?.members?.length; i++) {
    const el = attrObj.members[i]
    if (config.useSID_id || config.useGUID_id) {
      const dn = await sidGuidToDn(baseEntity, el.value, ctx)
      if (!dn) throw new Error(`${action} error: sidGuidToDn() did not return any objectGUID value for dn=${el.value}`)
      el.value = dn
    }
    if (el.operation && el.operation === 'delete') { // delete member from group
      grp.remove[memberAttr].push(el.value) // endpointMapper returns URI encoded id because some IdP's don't encode id used in GET url e.g. Symantec/Broadcom/CA
    } else { // add member to group
      grp.add[memberAttr].push(el.value)
    }
  }

  const method = 'modify'
  let base
  if (config.useSID_id) base = `<SID=${id}>`
  else if (config.useGUID_id) base = `<GUID=${id}>`
  else base = id // dn

  try {
    delete attrObj.members
    const [endpointObj] = scimgateway.endpointMapper('outbound', attrObj, config.map.group)
    const newDN = checkIfNewDN(baseEntity, base, 'group', attrObj, endpointObj)
    if (Object.keys(endpointObj).length > 0) {
      const ldapOptions = {
        operation: 'replace',
        modification: endpointObj,
      }
      await doRequest(baseEntity, method, base, ldapOptions, ctx)
    }
    if (grp.add[memberAttr].length > 0) {
      const ldapOptions = { // using ldap lookup (dn) instead of search
        operation: 'add',
        modification: grp.add,
      }
      await doRequest(baseEntity, method, base, ldapOptions, ctx)
    }
    if (grp.remove[memberAttr].length > 0) {
      const ldapOptions = { // using ldap lookup (dn) instead of search
        operation: 'delete',
        modification: grp.remove,
      }
      await doRequest(baseEntity, method, base, ldapOptions, ctx)
    }
    if (newDN && config.entity[baseEntity].ldap.allowModifyDN) {
      await doRequest(baseEntity, 'modifyDN', base, { modification: { newDN } }, ctx)
      const getObj = { attribute: 'id', operator: 'eq', value: newDN }
      const res = await scimgateway.getGroups(baseEntity, getObj, [], ctx)
      return res // return full group object to avoid scimgateway doing same getUser() using original id/dn that now will fail
    }
    return null
  } catch (err: any) {
    throw new Error(`${action} error: ${err.message}`)
  }
}

// =================================================
// helpers
// =================================================

const _serviceClient: Record<string, any> = {}

//
// createAndFilter creates AndFilter object to be used as filter instead of standard string filter
// Using AndFilter object for eliminating internal ldapjs escaping problems related to values with some
// combinations of parentheses e.g. ab(c)d
//
const createAndFilter = (baseEntity: string, type: string, arrObj: any) => {
  const objFilters: ldap.PresenceFilter[] | ldap.SubstringFilter[] = []

  // add arrObj
  for (let i = 0; i < arrObj.length; i++) {
    if (arrObj[i].value.indexOf('*') > -1) { // SubstringFilter or PresenceFilter
      const arr = arrObj[i].value.split('*')
      if (arr.length === 2 && !arr[0] && !arr[1]) { // cn=*
        const f = new ldap.PresenceFilter({ attribute: arrObj[i].attribute })
        objFilters.push(f)
      } else { // cn=ab*cd*e
        const fObj: any = {
          attribute: arrObj[i].attribute,
        }
        const arrAny: any = []
        fObj.initial = arr[0]
        if (!fObj.initial) delete fObj.initial
        for (let i = 1; i < arr.length - 1; i++) {
          arrAny.push(arr[i])
        }
        fObj.any = arrAny
        if (arr[arr.length - 1]) {
          fObj.final = arr[arr.length - 1]
        }
        const f = new ldap.SubstringFilter(fObj)
        objFilters.push(f)
      }
    } else { // EqualityFilter cn=abc
      const f = new ldap.EqualityFilter({ attribute: arrObj[i].attribute, value: arrObj[i].value })
      objFilters.push(f)
    }
  }

  // add from configuration objectClass and userFiter/groupFilter
  switch (type) {
    case 'user':
      for (let i = 0; i < config.entity[baseEntity].ldap.userObjectClasses.length; i++) {
        const f = new ldap.EqualityFilter({ attribute: 'objectClass', value: config.entity[baseEntity].ldap.userObjectClasses[i] })
        objFilters.push(f)
      }
      if (config.entity[baseEntity].ldap.userFilter) {
        try {
          const uf = ldap.parseFilter(config.entity[baseEntity].ldap.userFilter)
          objFilters.push(uf)
        } catch (err: any) {
          throw new Error(`configuration ldap.userFilter: ${config.entity[baseEntity].ldap.userFilter} - parseFilter error: ${err.message}`)
        }
      }
      break
    case 'group':
      for (let i = 0; i < config.entity[baseEntity].ldap.groupObjectClasses.length; i++) {
        const f = new ldap.EqualityFilter({ attribute: 'objectClass', value: config.entity[baseEntity].ldap.groupObjectClasses[i] })
        objFilters.push(f)
        if (config.entity[baseEntity].ldap.groupFilter) {
          try {
            const gf = ldap.parseFilter(config.entity[baseEntity].ldap.groupFilter)
            objFilters.push(gf)
          } catch (err: any) {
            throw new Error(`configuration ldap.groupFilter: ${config.entity[baseEntity].ldap.groupFilter} - parseFilter error: ${err.message}`)
          }
        }
      }
      break
  }

  // put all into AndFilter
  const filter = new ldap.AndFilter({
    filters: [
      ...objFilters,
    ],
  })

  return filter
}

//
// dnToSidGuid is used for Active Directory to return objectGUID based on dn
//
const dnToSidGuid = async (baseEntity: string, dn: any, ctx: any): Promise<string> => {
  const method = 'search'
  const ldapOptions: any = {}
  if (config.useSID_id) ldapOptions.attributes = ['objectSid']
  else if (config.useGUID_id) ldapOptions.attributes = ['objectGUID']
  else throw new Error('dnToSidGuid() invalid call, configuration not using objectSid or objectGUID')

  try {
    const base = dn
    const objects: any = await doRequest(baseEntity, method, base, ldapOptions, ctx)
    if (objects.length !== 1) throw new Error(`did not find unique object having dn=${base}`)
    if (config.useSID_id) return objects[0].objectSid
    else return objects[0].objectGUID
  } catch (err: any) {
    const newErr = new Error(`dnToSidGuid() ${err.message}`)
    throw newErr
  }
}

//
// guidToDn is used for Active Directory to return dn based on objectGUID
//
const sidGuidToDn = async (baseEntity: string, id: string, ctx: any): Promise<string> => {
  const method = 'search'
  const ldapOptions = {
    attributes: ['dn'],
  }
  try {
    let base
    if (config.useSID_id) {
      const sid = convertStringToSid(id)
      if (!sid) throw new Error(`sidGuidToDn() error: id=${id} - attribute having a none valid SID string`)
      base = `<SID=${sid}>`
    } else if (config.useGUID_id) {
      const guid = Buffer.from(id, 'base64').toString('hex')
      base = `<GUID=${guid}>`
    } else throw new Error('invalid call to sidGuidToDn(), configuration not using objectSid or objectGUID')
    const objects: any = await doRequest(baseEntity, method, base, ldapOptions, ctx)
    if (objects.length !== 1) throw new Error(`did not find unique object having ${config.useSID_id ? 'objectSid' : 'objectGUID'} =${id}`)
    return objects[0].dn
  } catch (err: any) {
    const newErr = new Error(`sidGuidToDN() ${err.message}`)
    throw newErr
  }
}

//
// convertSidToString converts hex encoded object SID to a string
// e.g.
// input: 0105000000000005150000002ec85f9ed78d59fa176c9e9c7a040000
// output: S-1-5-21-2657077294-4200173015-2627628055-1146
// ref: https://gist.github.com/Krizzzn/0ae47f280cca9749c67759a9adedc015
//
const pad = function (s: any) { if (s.length < 2) { return `0${s}` } else { return s } }
const convertSidToString = (buf: any) => {
  let asc: any, end: any
  let i: number
  if (buf == null) { return null }
  const version = buf[0]
  const subAuthorityCount = buf[1]
  const identifierAuthority = parseInt(((() => {
    const result: any = []
    for (i = 2; i <= 7; i++) {
      result.push(buf[i].toString(16))
    }
    return result
  })()).join(''), 16)
  let sidString = `S-${version}-${identifierAuthority}`
  try {
    for (i = 0, end = subAuthorityCount - 1, asc = end >= 0; asc ? i <= end : i >= end; asc ? i++ : i--) {
      const subAuthOffset = i * 4
      const tmp
        = pad(buf[11 + subAuthOffset].toString(16))
          + pad(buf[10 + subAuthOffset].toString(16))
          + pad(buf[9 + subAuthOffset].toString(16))
          + pad(buf[8 + subAuthOffset].toString(16))
      sidString += `-${parseInt(tmp, 16)}`
    }
  } catch (err) {
    return null
  }
  return sidString
}

//
// convertStringToSid converts SID string to hex encoded object SID
// e.g.
// input: S-1-5-21-2127521184-1604012920-1887927527-72713
// output: 010500000000000515000000a065cf7e784b9b5fe77c8770091c0100
// ref: https://devblogs.microsoft.com/oldnewthing/20040315-00/?p=40253
//
const convertStringToSid = (sidStr: string) => {
  const arr = sidStr.split('-')
  if (arr.length !== 8) return null
  try {
    const b0 = 0x0100000000000000n // S-1 = 01
    const b1 = 0x0005000000000000n // seven dashes, seven minus two = 5
    const b2 = BigInt(arr[2]) // 0x5n
    const b02 = b0 | b1 | b2 // big-endian
    const bufBE = Buffer.alloc(8)
    bufBE.writeBigUInt64BE(b02, 0)
    let res = bufBE.toString('hex') // 0105000000000005
    // rest is little-endian
    const bufLE = Buffer.alloc(4)
    for (let i = 3; i < arr.length; i++) {
      const val = parseInt(arr[i], 10 >>> 0) // int32 to unsigned int
      bufLE.writeUInt32LE(val, 0)
      res += bufLE.toString('hex')
    }
    return res
  } catch (err) {
    return null
  }
}

//
// getMemberOfGroups returns all groups the user is member of
// [{ id: <id-group>> , displayName: <displayName-group>, members [{value: <id-user>}] }]
//
const getMemberOfGroups = async (baseEntity: string, id: string, ctx: any) => {
  const action = 'getMemberOfGroups'
  if (!config.map.group) throw new Error('missing configuration endpoint.map.group') // not using groups

  let idDn = id
  if (config.useSID_id || config.useGUID_id) { // need dn
    const method = 'search'
    let base
    if (config.useSID_id) {
      const sid = convertStringToSid(id)
      if (!sid) throw new Error(`${action} error: ${id}=${id} - attribute having a none valid SID string`)
      base = `<SID=${sid}>`
    } else {
      const guid = Buffer.from(id, 'base64').toString('hex')
      base = `<GUID=${guid}>`
    }

    const ldapOptions = {
      attributes: ['dn'],
    }

    try {
      const users: any = await doRequest(baseEntity, method, base, ldapOptions, ctx)
      if (users.length !== 1) throw new Error(`${action} error: did not find unique user having ${config.useSID_id ? 'objectSid' : 'objectGUID'} =${id}`)
      idDn = users[0].dn
    } catch (err) {
      const newErr = err
      throw newErr
    }
  }

  const attributes = ['id', 'displayName']
  const [attrs, err] = scimgateway.endpointMapper('outbound', attributes, config.map.group) // SCIM/CustomSCIM => endpoint attribute naming
  if (err) throw err
  const [memberAttr, err1] = scimgateway.endpointMapper('outbound', 'members.value', config.map.group)
  if (err1) throw err1

  const method = 'search'
  const scope = 'sub'
  const base = config.entity[baseEntity].ldap.groupBase

  const filter = createAndFilter(baseEntity, 'group', [{ attribute: memberAttr, value: idDn }])
  const ldapOptions = {
    filter,
    scope,
    attributes: attrs,
  }

  try {
    const groups: any = await doRequest(baseEntity, method, base, ldapOptions, ctx)
    return groups.map((grp: any) => {
      return { // { id: <id-group>> , displayName: <displayName-group>, members [{value: <id-user>}] }
        id: encodeURIComponent(grp[attrs[0]]), // not mandatory, but included anyhow
        displayName: grp[attrs[1]], // displayName is mandatory
        members: [{ value: encodeURIComponent(id) }], // only includes current user
      }
    })
  } catch (err) {
    const newErr = err
    throw newErr
  }
}

//
// ldapEscDn will escape DN according to the LDAP standard adjusted to ldapjs behavior
// using OpenLDAP, DN must be escaped - national characters and special ldap characters
// using Active Directory (none OpenLDAP), DN should not be escaped, but DN retrieved from AD is character escaped
//
const ldapEscDn = (isOpenLdap: any, str: string) => {
  if (typeof str !== 'string' || str.length < 1) return str

  if (!isOpenLdap && str.indexOf('\\') > 0) {
    const conv = str.replace(/\\([0-9A-Fa-f]{2})/g, (_, hex) => {
      const intAscii = parseInt(hex, 16)
      if (intAscii > 128) { // extended ascii - will be unescaped by decodeURIComponent
        return '%' + hex
      } else { // use character escape
        return '\\' + String.fromCharCode(intAscii)
      }
    })
    str = decodeURIComponent(conv)
    str = str.replace(/\\/g, '') // lower ascii may be character escaped e.g. 'cn=Kürt\, Lastname' - see below comma logic
  }

  const arr = str.split(',')
  for (let i = 0; i < arr.length; i++) { // CN=Firstname, Lastname,OU=...
    if (!arr[i]) { // value having comma only
      if (arr[i - 1].charAt(arr[i - 1].length - 1) === '\\') {
        arr[i - 1] = arr[i - 1].substring(0, arr[i - 1].length - 1)
      }
      if (isOpenLdap) arr[i - 1] += '\\,'
      else arr[i - 1] += ','
      arr.splice(i, 1)
      i -= 1
      continue
    }
    const a = arr[i].split('=')
    if (a.length < 2 && i > 0) { // value having comma and content
      if (arr[i - 1].charAt(arr[i - 1].length - 1) === '\\') {
        arr[i - 1] = arr[i - 1].substring(0, arr[i - 1].length - 1)
      }
      if (isOpenLdap) arr[i - 1] += `\\,${ldapEsc(a[0])}`
      else arr[i - 1] += `,${a[0]}`
      arr.splice(i, 1)
      i -= 1
      continue
    } else {
      if (isOpenLdap) arr[i] = `${a[0]}=${ldapEsc(a[1])}`
      else arr[i] = `${a[0]}=${a[1]}`
    }
    if (i > 0) break // only escape logic on first, assume sub OU's are correct
  }
  if (isOpenLdap) {
    str = arr.join(',')
    return str
  }
  // Using dn object and BER encoding
  // e.g., Active Directory to avoid internal ldapjs OpenLDAP validating and string escaping logic
  const dn = new ldap.DN()
  for (let i = 0; i < arr.length; i++) {
    const a = arr[i].split('=') //