SCIM Gateway

The lib/saml directory contains a modified local copy of the node-saml package (v4.0.0). This local version is used instead of the standard npm package to ensure compatibility when SCIM Gateway plugins are compiled into standalone binaries using bun build --compile.

In the original node-saml package, XML templates were loaded from the file system using fs.readFileSync and __dirname. When compiled into a binary, these absolute paths from the build machine would fail on other machines (resulting in ENOENT errors). The local version solves this by inlining the XML templates as string constants directly within the code, removing the runtime dependency on external .template files.

Chain multiple gateways (gateway1 → gateway2 → gateway3 → endpoint). Each gateway validates authorization and forwards the request unless passThrough is enabled.

Gateway 1 configuration:

{
  "scimgateway": {
    "chainingBaseUrl": "https://gateway2:8880",
    "auth": {
      "passThrough": {
        "enabled": false
      }
    }
  }
}

In chaining mode, the plugin binary is only used for initialization. A simplified plugin implementation is sufficient:

import { ScimGateway } from 'scimgateway'
const scimgateway = new ScimGateway()
const config = scimgateway.getConfig()
scimgateway.authPassThroughAllowed = true
scimgateway.pluginAndOrFilterEnabled = false

To ensure SCIM Gateway starts automatically on Windows, create a task in Task Scheduler (taskschd.msc) with these settings:

Verification:

1. Confirm the process appears in Task Manager after running the task.
2. Confirm the process disappears after clicking 'End'.
3. Confirm auto-start after a system reboot.

To create a custom plugin for SCIM Gateway, follow these steps:

1. Scaffold: Copy an existing example plugin (e.g., lib/plugin-mssql.ts and config/plugin-mssql.json) and rename them with your own prefix (e.g., plugin-mine).
2. Configure: Set a unique port in your new configuration file (e.g., config/plugin-mine.json).
3. Register: Import your plugin in index.ts using import './lib/plugin-mine.ts'.
4. Initialize: Ensure you perform the mandatory plugin initialization in your entry point.
5. Verify: Start the gateway to confirm the plugin is loaded.

Recommended Editor: Visual Studio Code is recommended as it provides IntelliSense for all scimgateway methods.

// Example registration in index.ts
import './lib/plugin-mine.ts';

You can start the SCIM Gateway using bun. Depending on your directory structure, use one of the following commands:

# If in the package root
bun .

# Using the absolute path to the directory
bun c:\my-scimgateway

# Using the path to the entrypoint
bun c:\my-scimgateway\index.ts

Press Ctrl+C to stop the process.

To install SCIM Gateway, you must first have Bun installed. The installation process initializes a new project and copies example files (including index.ts, lib/, and config/) into your directory.

Note: Running bun pm trust scimgateway is required to allow the postinstall script to copy these example files into your package directory.

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

Plugins are defined by an entry point in index.ts and a corresponding configuration file. Each plugin requires a TypeScript file and a JSON configuration file that share the same name prefix.

Example structure:

• lib/plugin-entra-id.ts
• config/plugin-entra-id.json

The JSON configuration file must contain two top-level objects:

1. scimgateway: Contains gateway core settings (port, auth, logging, TLS).
2. endpoint: Contains plugin-specific connection details (host, credentials, mappings).

To start one or more plugins, import them in your index.ts entry point.

// Start one or more plugins:
import './lib/plugin-entra-id.ts'
export {}

The recommended upgrade path is to rename your existing package folder, perform a fresh installation, and then manually copy your customized index.ts, config/, and lib/ files from the old installation to the new one.

Minor upgrade:

bun install scimgateway

Major upgrade:

bun install scimgateway@latest

Note: Major upgrades may break existing plugins. Review the changelog before proceeding.

Production Note: To exclude example plugins in production environments using npm or Node.js, set the environment variable SCIMGATEWAY_POSTINSTALL_SKIP=true or add scimgateway_postinstall_skip = true to your .npmrc file.

# Minor upgrade
bun install scimgateway

# Major upgrade
bun install scimgateway@latest