Registry / auth-security / samlp
library8.0.0jsnpmunverified

samlp is a Node.js middleware library designed to facilitate the creation of SAML Protocol Identity Provider (IdP) endpoints. It handles the complexities of generating SAML responses and metadata, allowing developers to focus on user authentication mechanisms. The current stable version is 8.0.0, released March 31, 2026. This library is actively maintained by Auth0 and sees releases for new features, bug fixes, and dependency updates, typically on a monthly to quarterly cadence. Its key differentiator is its focus specifically on the IdP side of SAML, providing a configurable Express/Koa-compatible middleware, in contrast to libraries that are more general-purpose or service provider-centric. It requires Node.js version 12 or greater, reflecting modern Node.js ecosystem practices.

npm install samlp
INSTALL
IMPORT
SIG · SAMLP
S
samlp
auth-securityjavascriptv8.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 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.
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.
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.
fix
Ensure 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.
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`).
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.
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)`.
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.
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.
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.
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')
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)
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 ...
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.
Upgrade
Version history
8.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources