passport-saml: a SAML 2.0 strategy for Passport on Node

The service provider side, and what you have to bring

The description of the role is short and it fixes the scope. Passport-SAML is the service provider side of a SAML login, so it sends users to your identity provider to log in and validates the response the identity provider sends back. The package installs with a single command:

npm install @node-saml/passport-saml

The setup sequence is the one every SAML integration needs, and the readme states it plainly. You register your site with the identity provider first, and most providers accept the metadata that Passport-SAML generates. From the provider you need its single sign-on URL for the entry point and its signing certificate for the certificate option. That is the whole configuration handshake, and the reason a generated metadata document matters is that it removes the need to hand-write the entity id, the assertion consumer service URL and the certificate list, which is where most first-time SAML mistakes are made. The readme also states which providers this has been tested against, and that list is worth reading before you commit, because SAML implementations differ in the details even when they claim to be compliant.

The strategy constructor and the parameters that are not just pass-through

Most of the strategy configuration is passed straight through to the underlying node-saml library, and the readme points at that library's documentation for the full list and for how the flows work. The parameters that belong to the strategy itself are described separately, and two of them matter. The pass request to callback option decides whether the request object is passed as the first argument to the verify callback, and it defaults to false, and it is the setting you need if your verify function has to look at the session, the host header or the original URL rather than only at the assertion. The name option lets you give the strategy a custom name, defaulting to saml, and it exists so you can instantiate the strategy more than once with different configurations, which is what lets one site authenticate against several SAML targets, with the requirement that each target gets its own set of URLs and that you pass the same custom name when calling authenticate. The additional parameters option takes a dictionary of extra query parameters to add to every request, and it is the one with a precedence rule attached, since a dictionary passed to authenticate overrides the ones set at initialisation.

Sign-on and logout are two separate callbacks with different rules

The verify function has two forms, one for signing on and one for logging out, and the example shows both in the constructor. The sign-on callback receives a profile and a done callback, and the rule is that calling done with a user logs the user in, while a missing user, whether null, undefined or false, fails the login, and calling done with an error reports an error. The profile holds the assertion's name identifier and attributes, and the readme notes that the email property comes from an email or mail attribute if the identity provider sends one. The logout callback runs when the provider sends a logout request, and its rule is stricter and worth understanding before you ship it. Passport-SAML compares the user you return with the request's current user using a deep equality assertion, and it tells the identity provider the logout succeeded only if they match, though the current session is logged out either way. The security consequence is that an attacker who can make the callback return a different user gets a logout that the provider believes failed, which is a deliberate choice to avoid logging the wrong person out of the provider side.

Multiple identity providers need a different strategy class

The single-provider strategy assumes one configuration, and the readme gives a separate class for the multi-provider case. You use the multi strategy and pass it a function that returns the SAML options for the request, and that function runs on every request that reaches the strategy, which is a performance consideration if your provider lookup is a database call. The callback signatures change as a result, with the request passed into both the sign-on and the logout functions, and the pass request to callback option is set to true in the example for that reason. The options are then resolved per request from whatever your lookup returns, which is what makes a site able to serve several organisations, each with its own identity provider and its own certificate. The readme also mentions that the strategy can be instantiated several times with different fixed configurations, which is the other way to solve the same problem, and the two approaches differ in that the multi strategy resolves the provider at request time while multiple instances pick it at startup.

Interoperability is a tested claim, not an assumed one

The readme lists the identity providers this has been tested to work with, and that list is the difference between a library you can try and one you can deploy. OneLogin, Okta, Shibboleth, SimpleSAMLphp based providers, and Active Directory Federation Services are all named, and the fact that Shibboleth and SimpleSAMLphp are both listed matters because they are the two most common academic and research identity providers and they are not identical in their quirks. ADFS is listed separately because it is the Microsoft stack that enterprise shops actually run, and its quirks are well known. The library is published to npm under the node-saml scope, the licence is MIT, and the repository carries the badges you would expect from a security library, with a build status, a CodeQL analysis workflow, a codecov report, a DeepScan grade and a link to the node version support policy. The CodeQL and the static analysis badges are worth noticing for a package that parses XML assertions, since the analysis is the kind of thing that catches an issue in a dependency you did not write.

The build and release machinery behind the package

The package metadata shows a TypeScript source compiled to a CommonJS library, with the build script running the TypeScript compiler and a prepare script that runs it as well so that a git install works. The lint script runs eslint over the TypeScript sources with a cache and then a separate prettier check, and there are watch variants of both driven by a file watcher. The test script runs the compiler and then mocha under the coverage tool, and the release is driven by release-it, with a prerelease script that does a hard clean, a fresh install, the lint, the tests and the build, so a published package cannot come out of a dirty tree. The changelog is generated with gren from the commit history, which means the release notes and the commits are the same source of truth. The dependencies are few, with the node-saml library doing the actual protocol work and the rest being the Passport integration, so the attack surface of the strategy itself is small, which is the right shape for the layer that touches identity assertions.

Editorial conclusion

passport-saml is a good fit for a Node application that already authenticates with Passport and needs to accept a corporate or institutional identity provider, because it slots in as one more strategy rather than a parallel authentication system, and the multi-provider variant covers the case of a site serving several organisations. It is the wrong tool if you are building a new application with no Passport dependency, since the underlying node-saml library can be used directly, and it is the wrong tool if you need anything beyond SAML 2.0, since there is no support for other federation protocols here. It is also the wrong tool if you expect the library to resolve your users, because it hands you a profile and expects you to look the account up, and that lookup is where your security decisions live. Before deploying it, read the logout behaviour, because the confirmation of a logout to the identity provider only happens when the returned user matches the session, and the last push was on 2026-10-05 with the current release v5.1.1 from 2026-09-28.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. node-saml/passport-saml on GitHub
4. README
5. Releases