SAML Jackson (Polis)

@boxyhq/saml-jackson is the npm library at the core of Ory Polis (formerly BoxyHQ Jackson): it implements SAML 2.0 and OpenID Connect single sign-on as a standard OAuth 2.0 authorization-code flow, so application developers never have to parse a SAML assertion, sign XML, or handle IdP metadata directly. It also ships a Directory Sync engine built on the SCIM 2.0 protocol for automatically provisioning and de-provisioning users and groups as an identity provider’s directory changes.

The library is framework-agnostic and designed to be embedded into any Node.js server — Express, Next.js, or a custom backend — with a bring-your-own-database model covering Postgres, MySQL, MariaDB, MSSQL, MongoDB, DynamoDB, PlanetScale, Redis, and SQLite. It is the exact code that powers both self-hosted and cloud deployments of Ory Polis.

What You Get

• SAML-to-OAuth bridge - converts a SAML 2.0 IdP login into a standard OAuth 2.0 authorization-code flow your app already knows how to handle
• OIDC identity-provider support - accepts OpenID Connect IdPs through the same connection and controller API used for SAML
• Directory Sync (SCIM 2.0) - provisions and de-provisions users and groups automatically as an IdP’s directory changes
• Bring-your-own-database - ships drivers for Postgres, MySQL, MariaDB, MSSQL, MongoDB, DynamoDB, PlanetScale, Redis, and SQLite
• SSO trace logging - records SAML/OIDC login attempts with a configurable TTL for debugging failed enterprise logins

Common Use Cases

• Adding enterprise SSO to a SaaS product - a startup embeds @boxyhq/saml-jackson in its Node.js backend so enterprise customers can log in with Okta, Azure AD, or Google Workspace via SAML without writing SAML-parsing code
• Self-hosted directory sync - an ops team wires up the SCIM 2.0 endpoints so a customer’s IdP automatically creates and removes user accounts as employees join or leave
• Multi-tenant identity federation - a platform uses the identity-federation controller so one upstream IdP connection can serve as the SSO source for several downstream tenants or products
• Framework-agnostic SSO middleware - a team wraps the exported controllers (oauthController, apiController, directorySyncController) inside Express or Next.js API routes to add SSO without adopting a full IAM platform

Under The Hood

Architecture The library is organized as a factory function (controllers() in src/index.ts) that wires together a set of typed controllers — ConnectionAPIController, OAuthController, AdminController, LogoutController, SetupLinkController, OidcDiscoveryController, and the SCIM-based directorySyncController — on top of a pluggable persistence layer (src/db/db.ts) that normalizes many backends behind a common Storable/store.ts interface. Enterprise-only behavior — branding, identity federation, and product controllers — lives in a separate src/ee tree gated by checkLicense.ts, keeping the open-source and licensed code paths clearly separated. Because everything is assembled through one async factory call, the core abstraction (the DB wrapper) is what would ripple outward if changed: every controller depends on it for reads, writes, and encryption of stored connection data.

Tech Stack Written in TypeScript, the library uses TypeORM for its SQL backends (Postgres, MySQL, MariaDB, MSSQL, SQLite) alongside dedicated drivers for MongoDB, Redis, DynamoDB (via the AWS SDK), and PlanetScale. Protocol work is handled by @boxyhq/saml20 for SAML XML signing/parsing, openid-client for OIDC, and jose/node-forge for JWT and X.509 certificate handling; @googleapis/admin supports Google Workspace directory sync, and OpenTelemetry-based metrics are built in for observability.

Code Quality Tests live under test/, organized by feature area (sso, dsync, sso-traces, identity-federation, setup-link), and run on the tap framework with sinon and nock used to stub HTTP and time-dependent behavior. A map.js coverage map is wired into the tap config, though the test script explicitly allows incomplete coverage rather than enforcing a hard threshold. A GitHub Actions workflow runs the suite on every push, and the wider repository carries an ESLint + Prettier setup.

API Design The public surface is unusually compact for what it does: a single controllers(opts) call returns every capability — OAuth, admin, directory sync, identity federation — as ready-to-use, consistently named controller instances, with sensible defaults for most options and only externalUrl and samlPath required. The trade-off is a fairly deep options object (nested db, openid, and ssoTraces groups) that a first-time integrator has to learn from the external docs site rather than from inline examples, since the README itself is minimal.