Passport-SAML

Passport-SAML is a SAML 2.0 authentication strategy for Passport, the Node.js authentication middleware. It lets an Express (or any Passport-compatible) application act as a SAML service provider, redirecting users to an identity provider for single sign-on and validating the resulting SAML assertions before handing control back to the application’s own verify callback.

The package has been tested against OneLogin, Okta, Shibboleth, SimpleSAMLphp, and Active Directory Federation Services, and ships a MultiSamlStrategy variant that resolves SAML configuration per-request so a single strategy instance can serve multiple identity providers or tenants from one codebase.

All core SAML protocol handling (XML parsing, signature and certificate validation, assertion decryption) is delegated to the sibling @node-saml/node-saml library; Passport-SAML itself is a thin, fully-typed adapter that maps that protocol logic onto Passport’s authenticate/success/fail/error strategy contract.

What You Get

• A Strategy class that handles SP-initiated login, IdP callback validation, and single logout (SLO) for one configured identity provider
• A MultiSamlStrategy class that resolves SAML configuration per-request via a getSamlOptions callback, enabling one process to serve many IdPs or tenants
• Support for HTTP-Redirect and HTTP-POST SAML bindings, including automatic form generation for POST-bound authentication requests
• generateServiceProviderMetadata() for producing SP metadata XML that IdPs use to establish trust
• Full TypeScript type definitions for strategy options, verify callbacks, and SAML profile shapes, re-exported from the underlying @node-saml/node-saml package

Common Use Cases

• Adding enterprise SSO login to an Express/Node app so employees authenticate through their corporate IdP (Okta, ADFS, OneLogin) instead of a local password
• Building a B2B SaaS product where each customer organization brings its own SAML identity provider, using MultiSamlStrategy to route each request to the right IdP configuration
• Integrating with Active Directory Federation Services for internal line-of-business applications
• Implementing SAML single logout (SLO) so a session ends across both the service provider and identity provider when a user signs out

Under The Hood

Architecture The package exports Strategy and MultiSamlStrategy (src/strategy.ts, src/multiSamlStrategy.ts), both extending a shared AbstractStrategy base that itself extends passport-strategy’s Strategy. AbstractStrategy.authenticate() inspects the incoming request for a SAMLResponse/SAMLRequest in the query string or body and dispatches to the corresponding @node-saml/node-saml validation method (validateRedirectAsync, validatePostResponseAsync, validatePostRequestAsync), then routes the resulting profile through user-supplied signon/logout verify callbacks that mirror Passport’s conventional (err, user, info) contract. MultiSamlStrategy overrides authenticate/logout/generateServiceProviderMetadata to first resolve per-request configuration through a caller-supplied getSamlOptions(req, done) callback, construct a fresh SAML instance from the resolved options, and then delegate to the parent implementation via prototype-swapping (Object.setPrototypeOf) rather than duplicating logic. Because essentially all SAML protocol work (XML parsing, signature/certificate validation, assertion decryption) is delegated to the sibling node-saml package, this library itself is a comparatively thin adapter layer between that protocol engine and Passport’s strategy interface — replacing the underlying SAML validation would mean changing node-saml, not this package.

Tech Stack Written entirely in TypeScript (strict mode, ES2018/CommonJS output via tsc), the runtime dependency surface is deliberately narrow: @node-saml/node-saml for SAML protocol logic, passport and passport-strategy for the Passport plugin contract, and @types/express/@types/passport for request typing. There is no database or persistence layer — session/state caching for validateInResponseTo is delegated to node-saml’s pluggable cache providers. Tooling includes ESLint with typescript-eslint, Prettier (enforced via prettier-plugin-packagejson), Mocha/Chai/Sinon for tests with nyc coverage reporting to Codecov, and release-it plus a GitHub-Actions changelog generator for releases.

Code Quality Two substantial spec files (test/strategy.spec.ts, test/multiSamlStrategy.spec.ts, roughly 370-380 lines each) exercise both strategy classes against a test/static fixture set of real certificates, keys, and sample SAML XML requests/responses — including a deliberately-broken signature fixture used to assert failure handling. TypeScript strict mode is enabled project-wide, errors are surfaced through Passport’s this.error()/thrown Error objects rather than swallowed, and CI runs a build-and-test workflow plus CodeQL security scanning on every push and pull request. No test files were found for the docs/example script, but the library’s own source is well covered.

What Makes It Unique Passport-SAML’s main differentiator versus generic SAML client libraries is MultiSamlStrategy: rather than hard-coding one identity provider per strategy instance, it resolves the SAML configuration dynamically per incoming request, which is what makes a single-tenant-per-strategy pattern usable for multi-tenant B2B SaaS products serving many customer IdPs from one process. The project also deliberately keeps this package as a thin Passport adapter and pushes all protocol logic into a separately maintained node-saml module, so the two can evolve and be audited independently — a pragmatic separation-of-concerns choice more than a novel algorithm.