SCIM Gateway

Author: Jarle Elshaug

Validated through IdP's:

• Symantec/Broadcom/CA Identity Manager
• Microsoft Entra ID
• One Identity Manager/OneLogin
• Okta
• Omada
• SailPoint/IdentityNow

Latest news:

• Major version v5.0.0 marks a shift to native TypeScript support and prioritizes Bun over Node.js. This upgrade requires some modifications to existing plugins.
• BREAKING: 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. Kubernetes health checks and shutdown handler support
• Supports OAuth Client Credentials authentication
• Major version v4.0.0 getUsers() and getGroups() replacing some deprecated methods. No limitations on filtering/sorting. Admin user access can be linked to specific baseEntities. New MongoDB plugin
• ipAllowList for restricting access to allowlisted IP addresses or subnets e.g. Azure IP-range
• General LDAP plugin configured for Active Directory
• PlugSSO using SCIM Gateway
• Each authentication configuration allowing more than one admin user including option for readOnly
• Codebase moved from callback of h... to the the promise(d) land of async/await
• Supports configuration by environments and external files
• Health monitoring through "/ping" URL, and option for error notifications by email
• Entra ID user provisioning including license management e.g. Office 365, installed and configured within minutes!
• Includes API Gateway for none SCIM/provisioning - becomes what you want it to become
• Running SCIM Gateway as a Docker container

Overview

With SCIM Gateway, user management is facilitated through the utilization of the REST-based SCIM 1.1 or 2.0 protocol. The gateway acts as a translator for incoming SCIM requests, seamlessly enabling the exposure of CRUD functionality (create, read, update, and delete user/group) towards destinations. This is achieved through the implementation of endpoint-specific protocols, ensuring precise and efficient provisioning with diverse endpoints.

SCIM Gateway is based on popular asynchronous event driven framework Bun or Node.js using TypeScript/JavaScript. It is cloud and firewall friendly. Runs on almost all operating systems, and may load balance between hosts (horizontal) and cpu's (vertical).

Following example plugins are included:

• Loki (NoSQL Document-Oriented Database)
  SCIM Gateway becomes a standalone SCIM endpoint
  Demonstrates user provisioning towards document-oriented database
  Using LokiJS for a fast, in-memory document-oriented database (much like MongoDB/PouchDB)
  Default gives two predefined test users loaded using in-memory only (no persistence)
  Configuration {"persistence": true} gives persistence file store (no test users)
  Example of a fully functional SCIM Gateway plugin

• MongoDB (NoSQL Document-Oriented Database)
  Same as plugin "Loki", but using external MongoDB
  Shows how to implement a highly configurable multi tenant or multi endpoint solution through baseEntity in URL

• SCIM (REST Webservice)
  Demonstrates user provisioning towards REST-Based endpoint (type SCIM)
  Using plugin Loki as SCIM endpoint
  Can be used as SCIM version-gateway e.g. 1.1=>2.0 or 2.0=>1.1
  Can be used to chain several gateways

• Soap (SOAP Webservice)
  Demonstrates user provisioning towards SOAP-Based endpoint
  Example WSDLs are included
  Using endpoint "Forwardinc" as an example (comes with Symantec/Broadcom/CA IM SDK - SDKWS)
  Shows how to implement a highly configurable multi tenant or multi endpoint solution through baseEntity in URL

• MSSQL (MSSQL Database)
  Demonstrates user provisioning towards MSSQL database

• SAP HANA (SAP HANA Database)
  Demonstrates SAP HANA specific user provisioning

• Entra ID (REST Webservices)
  Entra ID user provisioning including license management (App Service plans) e.g. Office 365
  Using Microsoft Graph API
  Using customized SCIM attributes according to Microsoft Graph API
  Includes Symantec/Broadcom/CA ConnectorXpress metafile for creating provisioning "Azure - ScimGateway" endpoint type

• LDAP (Directory)
  Fully functional LDAP plugin
  Pre-configured for Microsoft Active Directory
  Using endpointMapper (like plugin-entra-id) for attribute mapping flexibility

• API (REST Webservices)
  Demonstrates API Gateway/plugin functionality using post/put/patch/get/delete
  None SCIM plugin, becomes what you want it to become.
  Methods included can also be used in standard SCIM plugins
  Endpoint complexity could be put in this plugin, and client could instead communicate through Gateway using your own simplified REST specification.
  One example of usage could be creation of tickets in ServiceDesk and also the other way, closing a ticket could automatically approve/reject corresponding workflow in IdP.

Installation

Install Bun

Bun is a prerequisite and must be installed on the server.

Note, Bun installs by default in the current user’s HOMEPATH\.bun. To install it elsewhere, set BUN_INSTALL= as a global or system environment variable before installing. The installation will add Bun to the current user’s path, but consider adding it to the global or system path for easier access across all users.

Install SCIM Gateway

Open a command window (run as administrator)
Create your own package directory e.g. c:\my-scimgateway and install SCIM Gateway within this package.

mkdir c:\my-scimgateway
cd c:\my-scimgateway
bun init -y
bun install scimgateway
bun pm trust scimgateway

c:\my-scimgateway will now be ``

index.ts, lib and config directories containing example plugins have been copied to your package from the original scimgateway package located under node_modules. Bun requires bun pm trust scimgateway for allowing postinstall copying these files.

If internet connection is blocked, we could install on another machine and copy the `` folder.

Startup and verify default Loki plugin

bun c:\my-scimgateway

If using Node.js instead of Bun, scimgateway must be downloaded from github and startup: node --experimental-strip-types c:\my-scimgateway\index.ts

Start a browser (note, Edge do not pop-up logon dialog box when using http)

https://localhost:8880/ping
=> Health check with a "hello" response

https://localhost:8880/Users  
https://localhost:8880/Groups 
=> Logon using gwadmin/password and two users and groups should be listed  

https://localhost:8880/Users/bjensen
https://localhost:8880/Groups/Admins
or
https://localhost:8880/Users?filter=userName eq "bjensen"
https://localhost:8880/Groups?filter=displayName eq "Admins"
=> Lists all attributes for specified user/group

https://localhost:8880/Groups?filter=displayName eq "Admins"&excludedAttributes=members
https://localhost:8880/Groups?filter=members.value eq "bjensen"&attributes=id,displayName,members.value
https://localhost:8880/Users?filter=userName eq "bjensen"&attributes=userName,id,name.givenName
https://localhost:8880/Users?filter=meta.created ge "2010-01-01T00:00:00Z"&attributes=userName,name.familyName,meta.created
https://localhost:8880/Users?filter=emails.value co "@example.com"&attributes=userName,name.familyName,emails&sortBy=name.familyName&sortOrder=descending
=> Filtering and attribute examples

"Ctrl + c" to stop the SCIM Gateway

>Tip, take a look at bun test scripts located in node_modules\scimgateway\test\lib

Upgrade SCIM Gateway

Not needed after a fresh install

The best and easiest way to upgrade is renaming existing scimgateway package folder, create a new one and do a fresh installation. After the installation we copy index.ts, config and lib folder (customized plugins) from previous installation to the new installation. You should also read the version history to see custom plugins needs to be updated.

Alternatives are:

Upgrade to latest minor version:

cd c:\my-scimgateway
bun install scimgateway

Note, always backup/copy c:\my-scimgateway before upgrading. Custom plugins and corresponding configuration files will not be affected.

To force a major upgrade (version x.*.* => y.*.*) that will brake compability with any existing custom plugins, we have to include the @latest suffix in the install command: bun install scimgateway@latest

Avoid (re-)adding the files created during postinstall

For production we do not need example plugins to be incuded by the postinstall job
Bun will by default exlude any postinstall jobs unless we have trusted the scimgateway package using the bun pm trust scimgateway that updates package.json { trustedDependencies: ["scimgateway"] }

For Node.js (and also Bun), we might set the property scimgateway_postinstall_skip = true in .npmrc or setting environment SCIMGATEWAY_POSTINSTALL_SKIP = true

Configuration

index.ts defines one or more plugins to be started by the const plugins setting.

// example starting all default plugins:
// const plugins = ['loki', 'scim', 'entra-id', 'ldap', 'mssql', 'api', 'mongodb', 'saphana', 'soap']

const plugins = ['ldap']

for (const plugin of plugins) {
  try {
    await import(`./lib/plugin-${plugin}.ts`)
  } catch (err: any) {
    console.error(`plugin-${plugin} startup error: ${err.message}`)
    console.log()
  }
}

Each endpoint plugin needs a TypeScript file (.ts) and a configuration file (.json). They both must have the same naming prefix. For SAP Hana endpoint we have:
>lib\plugin-saphana.ts
>config\plugin-saphana.json

Edit specific plugin configuration file according to your needs.
Below shows an example of config\plugin-saphana.json

{
  "scimgateway": {
    "port": 8884,
    "localhostonly": false,
    "payloadSize": null,
    "scim": {
      "version": "2.0",
      "skipTypeConvert" : false,
      "skipMetaLocation" false,
      "groupMemberOfUser": false
      "usePutSoftSync" : false
    },
    "log": {
      "loglevel": {
        "file": "debug",
        "console": "error"
      },
      "customMasking": []
    },
    "auth": {
      "basic": [
        {
          "username": "gwadmin",
          "password": "password",
          "readOnly": false,
          "baseEntities": []
        }
      ],
      "bearerToken": [
        {
          "token": null,
          "readOnly": false,
          "baseEntities": []
        }
      ],
      "bearerJwtAzure": [
        {
          "tenantIdGUID": null,
          "readOnly": false,
          "baseEntities": []
        }
      ],
      "bearerJwt": [
        {
          "secret": null,
          "publicKey": null,
          "options": {
            "issuer": null
           },
          "readOnly": false,
          "baseEntities": []
        }
      ],
      "bearerOAuth": [
        {
          "client_id": null,
          "client_secret": null,
          "readOnly": false,
          "baseEntities": []
        }
      ],
      "passThrough": {
         "enabled": false,
         "readOnly": false,
         "baseEntities": []
      }
    },
    "certificate": {
      "key": null,
      "cert": null,
      "ca": null,
      "pfx": {
        "bundle": null,
        "password": null
      }
    },
    "ipAllowList": [],
    "emailOnError": {
      "smtp": {
        "enabled": false,
        "host": null,
        "port": 587,
        "proxy": null,
        "authenticate": true,
        "username": null,
        "password": null,
        "sendInterval": 15,
        "to": null,
        "cc": null
      }
    },
    "stream": {
      "baseUrls": [],
      "certificate": {
        "ca": null
      },
      "subscriber": {
        "enabled": false,
        "entity": {
          "undefined": {
            "nats": {
              "tenant": null,
              "subject": null,
              "jwt": null,
              "secret": null
            },
            "deleteUserOnLastGroupRoleRemoval": false,
            "convertRolesToGroups": false,
            "generateUserPassword": false,
            "modifyOnly": false,
            "replaceDomains": []
          }
        }
      },
      "publisher": {
        "enabled": false,
        "entity": {
          "undefined": {
            "nats": {
              "tenant": null,
              "subject": null,
              "jwt": null,
              "secret": null
            }
          }
        }
      }
    }
  },
  "endpoint": {
    "host": "hostname",
    "port": 30015,
    "username": "username",
    "password": "password",
    "saml_provider": "saml_provider_name"
  }
}

Configuration file have two main JSON objects: scimgateway and endpoint

Definitions in scimgateway object have fixed attributes, but values can be modified. Sections not used/configured can be removed. This object is used by the core functionality of the SCIM Gateway.

Definitions in endpoint object are customized according to our plugin code. Plugin typically need this information for communicating with endpoint

• port - Gateway will listen on this port number. Clients (e.g. Provisioning Server) will be using this port number for communicating with the gateway.

• localhostonly - true or false. False means gateway accepts incoming requests from all clients. True means traffic from only localhost (127.0.0.1) is accepted.

• payloadSize - if not defined, default "1mb" will be used. There are cases which large groups could exceed default size and you may want to increase by setting your own size

• scim.version - "1.1" or "2.0". Default is "2.0".

• scim.skipTypeConvert - true or false, default false. Multivalue attributes supporting types e.g. emails, phoneNumbers, ims, photos, addresses, entitlements and x509Certificates (but not roles, groups and members) will be become "type converted objects" when sent to modifyUser and createUser. This for simplicity of checking attributes included and also for the endpointMapper method (used by plugin-ldap and plugin-entra-id), e.g.:

    "emails": {
      "work": {"value": "jsmith@example.com", "type": "work"},
      "home": {"value": "", "type": "home", "operation": "delete"},
      "undefined": {"value": "jsmith@hotmail.com"}
    }  
  
    skipTypeConvert set to true gives attribute "as-is": array, allow duplicate types including blank, but values to be deleted have been marked with "operation": "delete"
  
    "emails": [
      {"value": "jsmith@example.com", "type": "work"},
      {"value": "john.smith.org", "type": "home", "operation": "delete"},
      {"value": "jsmith@hotmail.com"}
    ]  
  

• scim.skipMetaLocation - true or false, default false. If set to true, meta.location which contains protocol and hostname from request-url, will be excluded from response e.g. "{...,meta":{"location":"https://my-company.com/<...>"}}. If using reverse proxy and not including headers X-Forwarded-Proto and X-Forwarded-Host, originator will be the proxy and we might not want to expose internal protocol and hostname being used by the proxy request.

• scim."groupMemberOfUser - true or false, default false. If body contains groups and groupMemberOfUser=true, groups attribute will remain at user object (groups are member of user) instead of default user member of groups that will use modifyGroup method for maintaining group members.

• scim.usePutSoftSync - true or false, default false. PUT /Users/bjensen will replace the user bjensen with body content. If set to true, only PUT body content will be replaced. Any additional existing user attributes and groups supported by plugin will remain as-is.

• log.loglevel.file - off, error, info, or debug. Output to plugin-logfile e.g. logs\plugin-saphana.log

• log.loglevel.console - off, error, info, or debug. Output to stdout and errors to stderr.

• log.customMasking - array of attributes to be masked e.g. "customMasking": ["SSN", "weight"]. By default SCIM Gateway includes masking of some standard attributes like password.

• auth - Contains one or more authentication/authorization methods used by clients for accessing gateway - may also include:

  • auth.xx.readOnly - true/false, true gives read only access - only allowing GET requests for corresponding admin user
  • auth.xx.baseEntities - array containing one or more baseEntity allowed for this user e.g. ["client-a"] - empty array allowing all.
    Methods are disabled by setting corresponding admin user to null or remove methods not used

• auth.basic - Array of one ore more basic authentication objects - Basic Authentication with username/password. Note, we set a clear text password that will become encrypted when gateway is started.

• auth.bearerToken - Array of one or more bearer token objects - Shared token/secret (supported by Entra ID). Clear text value will become encrypted when gateway is started.

• auth.bearerJwtAzure - Array of one or more JWT used by Azure SyncFabric. tenantIdGUID must be set to Entra ID Tenant ID.

• auth.bearerJwt - Array of one or more standard JWT objects. Using secret or publicKey for signature verification. publicKey should be set to the filename of public key or certificate pem-file located in \config\certs or absolute path being used. Clear text secret will become encrypted when gateway is started. options.issuer is mandatory. Other options may also be included according to jsonwebtoken npm package definition.

• auth.bearerOAuth - Array of one or more Client Credentials OAuth configuration objects. client_id and client_secret are mandatory. client_secret value will become encrypted when gateway is started. OAuth token request url is /oauth/token e.g. https://localhost:8880/oauth/token

• auth.passThrough - Setting auth.passThrough.enabled=true will bypass SCIM Gateway authentication. Gateway will instead pass ctx containing authentication header to the plugin. Plugin could then use this information for endpoint authentication and we don't have any password/token stored at the gateway. Note, this also requires plugin binary having scimgateway.authPassThroughAllowed = true and endpoint logic for handling/passing ctx.request.header.authorization

• certificate - If not using TLS certificate, set "key", "cert" and "ca" to null. When using TLS, "key" and "cert" have to be defined with the filename corresponding to the primary-key and public-certificate. Both files must be located in the \config\certs directory unless absolute path being defined e.g:

    "certificate": {
      "key": "key.pem",
      "cert": "cert.pem",
      "ca": null
    }  
  

  Example of how to make a self signed certificate:

    openssl req -nodes -newkey rsa:2048 -x509 -sha256 -days 3650 -keyout key.pem -out cert.pem -subj "/O=Testing/OU=SCIM Gateway/CN=" -config "