SAML Protocol Identity Provider Middleware

Common errors

• Error: certificate and private key do not match

  cause The public certificate (`cert`) and private key (`key`) provided to `samlp.auth` or `samlp.metadata` do not correspond to each other, or are malformed.
  fix Verify that `some-cert.pem` contains the public certificate corresponding to `some-cert.key`. Ensure both files are correctly formatted PEM files. Regenerate the key pair if necessary.

• TypeError: Cannot read properties of undefined (reading 'auth')

  cause Attempting to call `samlp.auth` or `samlp.metadata` without `samlp` being correctly imported or `samlp` itself being undefined.
  fix Ensure `import samlp from 'samlp';` or `const samlp = require('samlp');` is at the top of your file and executes correctly. This error can also happen if `samlp` is not properly installed (`npm install samlp`).

• SAML response not posting to Service Provider (blank page, or client-side error)

  cause The `getPostURL` function is returning an incorrect or inaccessible URL, or the Service Provider is not configured to receive SAML assertions at the specified endpoint.
  fix Double-check the implementation of your `getPostURL` function to ensure it returns the correct Assertion Consumer Service (ACS) URL for the target Service Provider. Verify that the Service Provider's ACS endpoint is correctly configured and publicly accessible.

• RangeError: The value of "node" is out of range. It must be >= 12. Received ...

  cause You are trying to run `samlp` on a Node.js version older than 12.
  fix Upgrade your Node.js environment to version 12 or higher. Use a Node.js version manager like `nvm` to easily switch and manage Node.js versions.

Warnings

• breaking Version 8.0.0 introduces new encryption algorithm options and a `disallowEncryptionWithInsecureAlgorithm` flag. The default encryption algorithm is now `http://www.w3.org/2009/xmlenc11#aes256-gcm`. If you were relying on implicit or less secure encryption algorithms, this might change behavior or require explicit configuration.
  Fix: Review and update your `encryptionAlgorithm` and `disallowEncryptionWithInsecureAlgorithm` options. If you need to use a different algorithm, explicitly set `encryptionAlgorithm`. To allow less secure algorithms (not recommended), set `disallowEncryptionWithInsecureAlgorithm` to `false` and consider `warnOnInsecureEncryptionAlgorithm` to `true` for logging.
• breaking Version 7.0.0 raised the minimum Node.js requirement to `node >= 12`. Older Node.js versions are no longer supported.
  Fix: Ensure your project is running on Node.js version 12 or newer. Update your Node.js environment if it's older.
• gotcha The `cert` and `key` options for the `samlp.auth` middleware are `REQUIRED` and must be valid PEM-encoded public and private keys, respectively. Misconfigured or missing keys are a common source of errors during SAML assertion signing or encryption.
  Fix: Always provide valid `cert` and `key` values as Buffer or string (from `fs.readFileSync`). Ensure the keys match and are correctly formatted. For development, you can generate self-signed certificates using OpenSSL (e.g., `openssl genrsa -out some-cert.key 2048`, `openssl req -new -x509 -key some-cert.key -out some-cert.pem -days 365`).
• gotcha The `getPostURL` option is `REQUIRED` and is a function that determines where the SAML assertion should be posted (the Service Provider's Assertion Consumer Service URL). Incorrect implementation or static URLs can lead to failed SAML flows or security vulnerabilities if not dynamically resolved.
  Fix: Implement `getPostURL` to dynamically resolve the correct ACS URL based on the SAML request's audience or other SP-identifying information. Avoid hardcoding this URL in production environments where multiple Service Providers might be interacting with your IdP. The function signature is `f(audience, samlRequestDom, req, callback)`.
• gotcha Security vulnerability fixes often involve upgrading underlying dependencies like `node-saml`. Older versions of `samlp` might contain known vulnerabilities inherited from these dependencies.
  Fix: Always keep `samlp` updated to the latest minor/patch versions within your major release, especially following dependency security updates (e.g., v7.0.2 fixed `node-saml` and `ejs` vulnerabilities, v7.1.1 fixed a signed logout response bug). Regularly check the release notes for security-related fixes.

Install

• npm install samlp npm
• yarn add samlp yarn
• pnpm add samlp pnpm

Imports

• samlp
  wrong:

  const samlp = require('samlp');

  correct:

  import samlp from 'samlp';

  While older versions might have been CJS-only, modern Node.js development strongly favors ESM. The library's `package.json` 'main' points to 'lib/samlp.js' which exports `module.exports`, so `require` is still the primary method for Node < 16 or mixed setups, but ESM import is increasingly preferred.
• auth
  wrong:

  import { auth } from 'samlp';

  correct:

  import samlp from 'samlp';
  app.get('/samlp', samlp.auth({...}));

  The `auth` method is a property of the default `samlp` export, not a named export. It's the primary entry point for configuring the SAML IdP authentication flow.
• metadata
  wrong:

  import { metadata } from 'samlp';

  correct:

  import samlp from 'samlp';
  app.get('/FederationMetadata/2007-06/FederationMetadata.xml', samlp.metadata({...}));

  Similar to `auth`, `metadata` is a property of the default `samlp` export, used for exposing the IdP's SAML metadata endpoint. Ensure correct path for the metadata endpoint.

Quickstart

This quickstart sets up a basic SAML Identity Provider (IdP) using Express and samlp, exposing login and metadata endpoints. It demonstrates how to configure the core `samlp.auth` middleware with required options like issuer, certificates, and a placeholder for the `getPostURL` and `getUserFromRequest` functions. It assumes a pre-authenticated `req.user` for simplicity. **Note**: Requires `some-cert.pem` and `some-cert.key` in the project root.

import express from 'express';
import samlp from 'samlp';
import fs from 'fs';
import path from 'path';

const app = express();
const PORT = process.env.PORT || 3000;

// Dummy user object for demonstration
const dummyUser = { id: 'user123', email: 'test@example.com', name: 'Test User' };

// Minimal SAMLP configuration
const samlpOptions = {
  issuer: 'http://localhost:3000/samlp',
  cert: fs.readFileSync(path.join(process.cwd(), 'some-cert.pem'), 'utf8'), // Ensure 'some-cert.pem' exists
  key: fs.readFileSync(path.join(process.cwd(), 'some-cert.key'), 'utf8'),   // Ensure 'some-cert.key' exists
  getPostURL: function (audience, samlRequestDom, req, callback) {
    // In a real scenario, this would dynamically determine the SP's AssertionConsumerService URL
    // For quickstart, we'll just return a placeholder or a mock SP URL.
    // Usually, the `audience` from SAMLRequest can help determine the SP.
    console.log('SAML Request received from audience:', audience);
    // For a minimal example, let's assume a fixed SP URL for posting the assertion
    const spAcsUrl = 'http://localhost:8080/saml/acs'; // Replace with a real SP's ACS URL
    return callback(null, spAcsUrl);
  },
  getUserFromRequest: function (req) {
    // In a real app, this would get the authenticated user from req.user or session
    return dummyUser;
  },
  profileMapper: samlp.PassportProfileMapper,
  signatureAlgorithm: 'rsa-sha256',
  digestAlgorithm: 'sha256',
  signResponse: false,
  signAssertion: true
};

app.get('/samlp', (req, res, next) => {
  // Simulate a pre-authenticated user for the IdP flow
  req.user = dummyUser;
  samlp.auth(samlpOptions)(req, res, next);
});

// SAML IdP Metadata endpoint
app.get('/samlp/FederationMetadata/2007-06/FederationMetadata.xml', samlp.metadata(samlpOptions));

app.listen(PORT, () => {
  console.log(`SAML IdP listening on port ${PORT}`);
  console.log('Access SAML Login Initiator via: http://localhost:3000/samlp');
  console.log('Access SAML Metadata via: http://localhost:3000/samlp/FederationMetadata/2007-06/FederationMetadata.xml');
});