This is a SAML 2.0 authentication provider for Passport, the Node.js authentication library.
Passport-SAML has been tested to work with Onelogin, Okta, Shibboleth, SimpleSAMLphp based Identity Providers, and with Active Directory Federation Services.
npm install @node-saml/passport-samlThe examples utilize the Feide OpenIdp identity provider. You need an account there to log in with this. You also need to register your site as a service provider.
The SAML identity provider will redirect you to the URL provided by the path configuration.
const SamlStrategy = require('passport-saml').Strategy;
[...]
passport.use(
new SamlStrategy(
{
path: "/login/callback",
entryPoint:
"https://openidp.feide.no/simplesaml/saml2/idp/SSOService.php",
issuer: "passport-saml",
cert: "fake cert", // cert must be provided
},
function (profile, done) {
// for signon
findByEmail(profile.email, function (err, user) {
if (err) {
return done(err);
}
return done(null, user);
});
},
function (profile, done) {
// for logout
findByNameID(profile.nameID, function (err, user) {
if (err) {
return done(err);
}
return done(null, user);
});
}
)
);You can pass a getSamlOptions parameter to MultiSamlStrategy which will be called before the SAML flows.
Passport-SAML will pass in the request object so you can decide which configuration is appropriate.
const { MultiSamlStrategy } = require('passport-saml');
[...]
passport.use(
new MultiSamlStrategy(
{
passReqToCallback: true, // makes req available in callback
getSamlOptions: function (request, done) {
findProvider(request, function (err, provider) {
if (err) {
return done(err);
}
return done(null, provider.configuration);
});
},
},
function (req, profile, done) {
// for signon
findByEmail(profile.email, function (err, user) {
if (err) {
return done(err);
}
return done(null, user);
});
},
function (req, profile, done) {
// for logout
findByNameID(profile.nameID, function (err, user) {
if (err) {
return done(err);
}
return done(null, user);
});
}
)
);The options passed when the MultiSamlStrategy is initialized are also passed as default values to each provider. e.g.
If you provide an issuer on MultiSamlStrategy, this will be also a default value for every provider. You can
override these defaults by passing a new value through the getSamlOptions function.
Using multiple providers supports validateInResponseTo, but all the InResponse values are stored on the same Cache.
This means, if you're using the default InMemoryCache, that all providers have access to it and a provider might get
its response validated against another's request. Issue Report.
To amend this you should provide a different cache provider per SAML provider, through the getSamlOptions function.
Please note that in the above examples, findProvider(), findByNameId(), and findByEmail() are examples of
functions you need to implement yourself. These are just examples. You can implement this functionality any way you see
fit. Please note that calling getSamlOptions() should result in done() being called with a proper SAML Configuration
(see the TypeScript typings for more information) and the done() callbacks for the second and third arguments should
be called with an object that represents the user.
These are only the additional configuration parameters related to passport-saml. For the full list of parameters,
please see the node-saml documentation
additionalParams: dictionary of additional query params to add to all requests; if an object with this key is passed toauthenticate, the dictionary of additional query params will be appended to those present on the returned URL, overriding any specified by initialization options' additional parameters (additionalParams,additionalAuthorizeParams, andadditionalLogoutParams)passReqToCallback: if truthy,reqwill be passed as the first argument to the verify callback (default:false)name: Optionally, provide a custom name. (default:saml). Useful If you want to instantiate the strategy multiple times with different configurations, allowing users to authenticate against multiple different SAML targets from the same site. You'll need to use a unique set of URLs for each target, and use this custom name when callingpassport.authenticate()as well.
You need to provide a route corresponding to the path configuration parameter given to the strategy:
The authentication callback must be invoked after the body-parser middleware.
const bodyParser = require("body-parser");
app.post(
"/login/callback",
bodyParser.urlencoded({ extended: false }),
passport.authenticate("saml", {
failureRedirect: "/",
failureFlash: true,
}),
function (req, res) {
res.redirect("/");
}
);Use passport.authenticate(), specifying saml as the strategy:
app.get(
"/login",
passport.authenticate("saml", { failureRedirect: "/", failureFlash: true }),
function (req, res) {
res.redirect("/");
}
);...or, if you wish to add or override query string parameters:
app.get(
"/login",
passport.authenticate("saml", {
additionalParams: { username: "user@domain.com" },
}),
function (req, res) {
res.redirect("/");
}
);For details about this method, please see the documentation
at node-saml.
The generateServiceProviderMetadata method is also available on the MultiSamlStrategy, but needs an extra request
and a callback argument (generateServiceProviderMetadata( req, decryptionCert, signingCert, next )), which are passed
to the getSamlOptions to retrieve the correct configuration.
Here is a configuration that has been proven to work with ADFS:
{
entryPoint: 'https://ad.example.net/adfs/ls/',
issuer: 'https://your-app.example.net/login/callback',
callbackUrl: 'https://your-app.example.net/login/callback',
idpCert: 'MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh ... W==',
authnContext: ['http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows'],
identifierFormat: null
}Please note that ADFS needs to have a trust established to your service in order for this to work.
For more detailed instructions, see ADFS documentation.
Passport-SAML has built in support for SLO from Node-SAML.
Note: Fully functional IdP initiated SLO support is not provided out of the box. You have to inspect your use cases / implementation / deployment scenarios (location of IdP in respect to SP) and consider things / cases listed e.g. at issue(s) #221 and #419. This library provides you a mechanism to veto "Success" result but it does not provide hooks/interfaces to implement support for IdP initiated SLO which would work under all circumstances. You have to do it yourself.
See Releases to find the changes that go into each release. Additionally, see the CHANGELOG.
Gerard Braad has provided an example app at https://github.com/gbraad/passport-saml-example/
We only support Long-Term Support versions of Node.
We specifically limit our support to LTS versions of Node, not because this package won't work on other versions, but because we have a limited amount of time, and supporting LTS offers the greatest return on that investment.
It's possible this package will work correctly on newer versions of Node. It may even be possible to use this package on older versions of Node, though that's more unlikely as we'll make every effort to take advantage of features available in the oldest LTS version we support.
As each Node LTS version reaches its end-of-life we will remove that version from the node engines property of our
package's package.json file. Removing a Node version is considered a breaking change and will entail the publishing of
a new major version of this package. We will not accept any requests to support an end-of-life version of Node. Any
merge requests or issues supporting an end-of-life version of Node will be closed.
We will accept code that allows this package to run on newer, non-LTS, versions of Node.
The project was started by @bergie in 2012 based on Michael Bosworth's express-saml library. From 2014 - 2016, @ploer served as primary maintainer. @markstos served the primary maintainer from 2017 till 2020 when he created the node-saml organization. With a goal to create a team of maintainers, invitations were sent to major contributors and fork authors to work together to maintain all the improvements in one place.
Since 2020, @cjbath emerged as the primary maintainer, with major contributions from @gugu and @zoellner. Major updates
from the team included rewriting the project in TypeScript and splitting off a node-saml module which can be used
without Passport. Almost 100 other developers have contributed improvements to the project.
The project continues to be maintained by volunteers. Contributions small and large are welcome.
“OASIS”, “SAML”, and “Security Assertion Markup Language” are trademarks of OASIS, the open standards consortium where the SAML specification is owned and developed. SAML is a copyrighted © work of OASIS Open. All rights reserved.