SAML and Enterprise SSO

import * as saml from 'samlify';

// Each enterprise customer is its own IdP configuration.
async function idpFor(domain) {
  const tenant = await db.tenants.findByEmailDomain(domain);
  if (!tenant?.samlEnabled) return null;
  return saml.IdentityProvider({
    metadata: tenant.samlMetadataXml,     // uploaded by the customer's IT
  });
}

const sp = saml.ServiceProvider({
  entityID: 'https://abc.com/saml/metadata',
  assertionConsumerService: [{
    Binding: saml.Constants.namespace.binding.post,
    Location: 'https://abc.com/saml/acs',
  }],
  wantAssertionsSigned: true,             // refuse unsigned assertions
  wantMessageSigned: true,
});

// SP-initiated: email domain decides where to send them
app.post('/login/sso', async (req, res) => {
  const domain = String(req.body.email).split('@')[1]?.toLowerCase();
  const idp = await idpFor(domain);
  if (!idp) return res.status(400).json({ error: 'sso_not_configured' });

  const { context } = sp.createLoginRequest(idp, 'redirect');
  res.redirect(context);
});

// The assertion arrives here
app.post('/saml/acs', express.urlencoded({ extended: false }), async (req, res) => {
  const idp = await idpFor(req.body.RelayStateDomain);
  let extract;
  try {
    // The library checks the signature, Conditions and Audience for you.
    ({ extract } = await sp.parseLoginResponse(idp, 'post', req));
  } catch {
    return res.status(400).json({ error: 'invalid_saml_response' });
  }

  // Replay protection: an assertion id may be consumed exactly once.
  const fresh = await db.samlAssertions.insertIfNew({
    id: extract.response.id,
    expiresAt: new Date(extract.conditions.notOnOrAfter),
  });
  if (!fresh) return res.status(400).json({ error: 'assertion_replayed' });

  // Just-in-time provisioning, with group → role mapping
  const user = await upsertSsoUser({
    email: extract.nameID,
    tenantId: req.tenant.id,
    roles: mapGroups(extract.attributes.groups ?? []),
  });

  res.cookie('sid', await createSession(user.id, req, { sso: true }), COOKIE_OPTIONS);
  res.redirect('/dashboard');
});

# Send them YOUR values (or a metadata URL that contains them)
  Entity ID / Audience URI :  https://abc.com/saml/metadata
  ACS URL / Reply URL      :  https://abc.com/saml/acs
  Name ID format           :  EmailAddress
  Metadata URL             :  https://abc.com/saml/metadata.xml

# Ask for THEIRS
  IdP metadata XML (or URL) — contains the sign-in URL, entity id and certificate

# Attributes to request in their mapping
  email       → NameID or an email attribute
  firstName / lastName
  groups      → mapped to your roles

# Test before going live
  1. SP-initiated login from your login page
  2. Wrong-tenant email → must not reach the IdP
  3. Expired assertion (NotOnOrAfter in the past) → rejected
  4. Replayed assertion → rejected
  5. Certificate rotation → both old and new accepted during the window
  6. Deprovision a user in the IdP → next login fails

# Certificate expiry is the #1 cause of 'SSO stopped working overnight'.
# Alert 30 days before, and support two certificates during rotation.