Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
samlp
✓ import samlp from 'samlp';
✗ const samlp = require('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
✓ import samlp from 'samlp';
app.get('/samlp', samlp.auth({...}));
✗ import { auth } from 'samlp';
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
✓ import samlp from 'samlp';
app.get('/FederationMetadata/2007-06/FederationMetadata.xml', samlp.metadata({...}));
✗ import { metadata } from 'samlp';
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.
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');
});
Debug
Known issues
breakingVersion 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.fixReview 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.
affects: >=8.0.0
breakingVersion 7.0.0 raised the minimum Node.js requirement to `node >= 12`. Older Node.js versions are no longer supported.fixEnsure your project is running on Node.js version 12 or newer. Update your Node.js environment if it's older.
affects: >=7.0.0
gotchaThe `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.fixAlways 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`).
affects: >=1.0.0
gotchaThe `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.fixImplement `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)`.
affects: >=1.0.0
gotchaSecurity vulnerability fixes often involve upgrading underlying dependencies like `node-saml`. Older versions of `samlp` might contain known vulnerabilities inherited from these dependencies.fixAlways 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.
affects: <7.0.2, <7.1.1 (for specific issues)
Errors
Common errors & fixes
Error: certificate and private key do not match
The public certificate (`cert`) and private key (`key`) provided to `samlp.auth` or `samlp.metadata` do not correspond to each other, or are malformed.
fixVerify 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')
Attempting to call `samlp.auth` or `samlp.metadata` without `samlp` being correctly imported or `samlp` itself being undefined.
fixEnsure `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)
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.
fixDouble-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 ...
You are trying to run `samlp` on a Node.js version older than 12.
fixUpgrade 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.
Audit
Dependencies
No dependency data recorded yet.