@node-saml/passport-saml

The MultiSamlStrategy class allows you to handle multiple SAML Identity Providers (IdPs) using a single Passport strategy. Instead of a static configuration, it uses a getSamlOptions function to dynamically resolve the specific SAML configuration based on the incoming request (e.g., by looking up a tenant ID or domain in the request URL or body).

To use it, you must provide a MultiStrategyConfig object that includes a getSamlOptions function. This function is called during the authenticate, logout, and generateServiceProviderMetadata lifecycles to inject provider-specific settings into the underlying SAML service.

import { MultiSamlStrategy } from '@node-saml/passport-saml';

const strategy = new MultiSamlStrategy({
  // Base configuration shared by all providers
  entryPoint: '', 
  issuer: 'my-app',
  // ... other PassportSamlConfig options

  // Dynamic configuration resolver
  getSamlOptions: (req, callback) => {
    const tenantId = req.params.tenantId;
    const providerConfig = lookupConfig(tenantId);

    if (providerConfig) {
      // Return the specific SAML options for this provider
      callback(null, {
        entryPoint: providerConfig.ssoUrl,
        issuer: providerConfig.issuer,
        // ...
      });
    } else {
      callback(new Error('Provider not found'));
    }
  }
}, signonVerify, logoutVerify);

The SamlStrategy is the primary class for single-provider SAML authentication. Most configuration options are passed through to the underlying node-saml library.

Passport-SAML specific parameters:

• additionalParams: A dictionary of additional query params to add to all requests. If passed to authenticate(), these override the initialization options.
• passReqToCallback: If true, the req object is passed as the first argument to the verify callback (default: false).
• name: A custom name for the strategy (default: saml). Use this if you need to instantiate multiple strategies with different configurations.

const SamlStrategy = require('@node-saml/passport-saml').Strategy;

passport.use(
  new SamlStrategy(
    {
      callbackURL: "/login/callback",
      entryPoint: "https://openidp.feide.no/simplesaml/saml2/idp/SSOService.php",
      issuer: "passport-saml",
      idpCert: "fake cert", // cert must be provided
    },
    function (profile, done) {
      // Sign-on callback: find or create user based on profile
      findByEmail(profile.email, function (err, user) {
        if (err) return done(err);
        return done(null, user);
      });
    },
    function (profile, done) {
      // Logout callback: find user based on profile
      findByNameID(profile.nameID, function (err, user) {
        if (err) return done(err);
        return done(null, user);
      });
    }
  )
);

Use MultiSamlStrategy when your application needs to support multiple different SAML Identity Providers (IdPs).

Key features:

• getSamlOptions: A function called before SAML flows. It receives the request object and a done callback. You must call done(null, configuration) with the specific SAML configuration for the detected provider.
• Defaults: Options provided during MultiSamlStrategy initialization act as defaults for all providers unless overridden in getSamlOptions.
• Caching Note: All providers share the same cache (e.g., InMemoryCache) by default. To prevent one provider from validating a response against another provider's request, provide a unique cache provider per SAML provider via getSamlOptions.

const { MultiSamlStrategy } = require('@node-saml/passport-saml');

passport.use(
  new MultiSamlStrategy(
    {
      passReqToCallback: true,
      getSamlOptions: function (request, done) {
        findProvider(request, function (err, provider) {
          if (err) return done(err);
          // Return the specific configuration for this provider
          return done(null, provider.configuration);
        });
      },
    },
    function (req, profile, done) {
      // Sign-on callback
      findByEmail(profile.email, function (err, user) {
        if (err) return done(err);
        return done(null, user);
      });
    },
    function (profile, done) {
      // Logout callback
      findByNameID(profile.nameID, function (err, user) {
        if (err) return done(err);
        return done(null, user);
      });
    }
  )
);

To initiate the SAML login flow, use passport.authenticate() with the saml strategy name.

Adding Query Parameters: You can pass additionalParams to authenticate() to append query string parameters to the redirect URL.

Handling Fallbacks: Use samlFallback (values: "login-request" or "logout-request") to dictate which request handler to use if the req.query or req.body does not contain standard SAMLRequest or SAMLResponse properties. The default is "login-request".

// Standard login
app.get(
  "/login",
  passport.authenticate("saml", { failureRedirect: "/", failureFlash: true }),
  function (req, res) {
    res.redirect("/");
  },
);

// Login with additional query parameters
app.get(
  "/login",
  passport.authenticate("saml", {
    additionalParams: { username: "user@domain.com" },
  }),
  function (req, res) {
    res.redirect("/");
  },
);