Handling Federation with SAML

In this lesson, you will learn how to integrate legacy enterprise Identity Providers (IdPs) into your Node.js backend using the Security Assertion Markup Language (SAML) protocol.

Understanding SAML Federation

While modern web apps favor OAuth2 or OIDC, many enterprise environments rely on SAML 2.0. In a SAML flow, your Node.js application acts as the Service Provider (SP). Instead of handling user credentials directly, you redirect the user to the company’s IdP (like Active Directory or Okta). The IdP validates the user and sends a cryptographically signed XML document—the SAML Assertion—back to your application.

Your job is to securely consume this assertion to establish a local session.

The Integration Workflow

1. Metadata Exchange: You and the enterprise IdP exchange metadata. They provide you with their signing certificate and SSO URL; you provide them with your EntityID and your "Assertion Consumer Service" (ACS) URL.
2. The Request: When a user clicks "Login with SSO," your Node.js app generates a <samlp:AuthnRequest>, encodes it, and redirects the browser to the IdP.
3. Verification: When the IdP POSTs the assertion to your ACS endpoint, you must:
   • Validate the XML signature against the IdP’s public certificate.
   • Check the Audience and Recipient tags to ensure the assertion was meant for your app.
   • Verify the timestamp to prevent replay attacks.

Concrete Implementation Logic

Using a library like passport-saml, you define your strategy to handle the verification logic:

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

passport.use(new SamlStrategy({
  path: '/login/callback',
  entryPoint: 'https://idp.enterprise.com/saml',
  issuer: 'my-node-app-id',
  cert: '...idp-public-signing-cert...'
}, (profile, done) => {
  // Map the SAML assertion attributes to your local user schema
  const user = { email: profile.nameID, id: profile.uid };
  return done(null, user);
}));

Once done() is called, the assertion has been verified, and you can proceed to issue your own local session token (e.g., a secure, HTTP-only cookie or JWT) to represent that user within your Node.js infrastructure.

Key Takeaway: SAML federation allows your Node.js application to delegate authentication to a trusted enterprise provider by verifying digitally signed XML assertions rather than handling user credentials directly.