Registry / auth-security / saml2-js

saml2-js

JSON →
library4.0.4jsnpmunverified

saml2-js is a Node.js module that simplifies the implementation of the SAML 2.0 protocol, specifically for acting as a Service Provider (SP). It abstracts away complexities, allowing applications to integrate with Identity Providers (IdPs) for authentication and authorization. The library currently does not support acting as an Identity Provider. As of version 4.0.4, the project is in maintenance mode, focusing primarily on addressing bug reports and security issues rather than feature development. There is no stated regular release cadence, with updates being driven by critical fixes. Key differentiators include its focus solely on SP functionality and a clear set of configuration options for managing SAML requests and responses. It offers constructors for `ServiceProvider` and `IdentityProvider` objects, with options for managing entity IDs, cryptographic keys, assertion endpoints, and various SAML-specific behaviors like `force_authn` and `nameid_format`.

auth-securityhttp-networking
npm install saml2-js
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · SAML2-JS
S
saml2-js
auth-securityjavascriptv4.0.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

saml2
✓ const saml2 = require('saml2-js');
✗ import saml2 from 'saml2-js';
The library primarily uses CommonJS `require` syntax. Direct ESM imports are not officially supported or documented for main exports.
ServiceProvider
✓ const { ServiceProvider } = saml2;
✗ import { ServiceProvider } from 'saml2-js';
ServiceProvider is a named export from the main `saml2` object, not a top-level import for CommonJS.
IdentityProvider
✓ const { IdentityProvider } = saml2;
✗ import { IdentityProvider } from 'saml2-js';
IdentityProvider is a named export from the main `saml2` object, not a top-level import for CommonJS.

This quickstart demonstrates how to configure a Service Provider and Identity Provider, generate a SAML login request URL for SP-initiated SSO, and generate SP metadata for IdP configuration.

const saml2 = require('saml2-js'); const fs = require('fs'); const path = require('path'); // In a real application, these would be loaded securely (e.g., from environment variables). // For demonstration, using dummy values and assuming keys/certs exist. const spPrivateKey = process.env.SP_PRIVATE_KEY ?? '-----BEGIN RSA PRIVATE KEY-----\n...your_private_key...\n-----END RSA PRIVATE KEY-----'; const spCertificate = process.env.SP_CERTIFICATE ?? '-----BEGIN CERTIFICATE-----\n...your_certificate...\n-----END CERTIFICATE-----'; const idpCertificate = process.env.IDP_CERTIFICATE ?? '-----BEGIN CERTIFICATE-----\n...idp_certificate...\n-----END CERTIFICATE-----'; // Service Provider (SP) options const spOptions = { entity_id: "https://sp.example.com/metadata", private_key: spPrivateKey, certificate: spCertificate, assert_endpoint: "https://sp.example.com/sso/assert" }; // Identity Provider (IdP) options (minimal for login request) const idpOptions = { entity_id: "https://idp.example.com/saml/metadata", sso_login_url: "https://idp.example.com/saml/sso", certificates: [idpCertificate] }; // Instantiate SP and IdP const sp = new saml2.ServiceProvider(spOptions); const idp = new saml2.IdentityProvider(idpOptions); // Generate a SAML login request URL (for SP-initiated SSO) sp.create_login_request_url(idp, {}, (err, loginUrl, requestId) => { if (err) { console.error("Error creating login request URL:", err); return; } console.log("SAML Login Request URL:\n", loginUrl); console.log("Request ID:", requestId); // In a web application, you would redirect the user to this loginUrl. // e.g., res.redirect(loginUrl); }); // Example of generating SP metadata (to provide to the IdP) sp.create_metadata((err, metadata) => { if (err) { console.error("Error creating SP metadata:", err); return; } console.log("\nService Provider Metadata:\n", metadata); });
Debug
Known issues
gotchaThe `saml2-js` library is officially in maintenance mode, meaning active feature development has ceased. The focus is exclusively on critical bug fixes and security updates. New features or significant architectural changes are unlikely.
fix
Developers requiring new SAML features or extensive support should consider alternative, actively developed SAML libraries for Node.js.
affects: >=4.0.0
gotchaSetting `allow_unencrypted_assertion` to `true` allows the Service Provider to accept SAML assertions that are not encrypted. This can expose sensitive user data in transit if not mitigated by other transport-level security measures (e.g., HTTPS).
fix
Ensure `allow_unencrypted_assertion` is `false` in production environments unless explicitly required and protected by robust transport-level security. Always use HTTPS for SAML communication.
affects: >=2.0.0
gotchaIncorrect configuration of `notbefore_skew` (or its omission) can lead to valid SAML assertions being rejected due to minor clock differences between the Identity Provider and Service Provider, or, conversely, create a window for replay attacks if set too high.
fix
Tune `notbefore_skew` carefully. Start with a small positive integer (e.g., 60 seconds) and monitor logs. Avoid setting it to a very large number, which could compromise security. Synchronize server clocks (NTP) for both IdP and SP.
affects: >=2.0.0
gotchaThe `audience` option is critical for validating SAML assertions. If not correctly configured to match the `<Audience>` values sent by the IdP, assertions will be rejected, leading to authentication failures.
fix
Verify that the `audience` specified in the `ServiceProvider` configuration (or defaulted to `entity_id`) exactly matches one of the `<Audience>` values present in the IdP's SAML responses.
affects: >=2.0.0
gotchaSecurely managing `private_key` and `certificate` is paramount. Exposing the private key compromises the security of your Service Provider and could allow an attacker to impersonate your SP or decrypt assertions.
fix
Load keys and certificates from secure environment variables, a secret management service, or encrypted files. Ensure private keys have restricted file system permissions. Implement key rotation policies.
affects: >=1.0.0
gotchaThis library is designed solely for Service Provider (SP) functionality and explicitly *does not* implement features to act as an Identity Provider (IdP). Attempting to use it as an IdP will not work.
fix
If Identity Provider functionality is required, select a different SAML library specifically designed for IdP implementations.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: saml2.ServiceProvider is not a constructor
Attempting to destructure or import `ServiceProvider` directly using ESM syntax or incorrect CommonJS requiring.
fix
Use `const saml2 = require('saml2-js');` and then `new saml2.ServiceProvider(...)`.
Error: Required option 'entity_id' not provided for ServiceProvider
Missing the mandatory `entity_id` property in the `ServiceProvider` constructor options.
fix
Provide a unique identifier string for `entity_id` in the `ServiceProvider` options object.
Error: SAML Assertion Audience Restriction mismatch. Expected [expected_audience], received [received_audience].
The `audience` configured in the `ServiceProvider` does not match any of the `<Audience>` values within the SAML assertion received from the IdP.
fix
Update the `audience` option in `ServiceProvider` to precisely match one of the valid audience values provided by the Identity Provider.
Error: SAML Assertion NotBefore condition invalid. Current time: [timestamp], NotBefore: [notbefore_timestamp]
The current system time on the Service Provider is earlier than the `NotBefore` timestamp in the SAML assertion, indicating a clock skew issue or a replay attack attempt.
fix
Synchronize the server clocks using NTP. Consider increasing the `notbefore_skew` option in `ServiceProvider` slightly (e.g., to 60 seconds) to tolerate minor clock differences.
Error: Decryption failed for SAML assertion. Bad padding or invalid key.
The Service Provider's private key (`private_key` option) is incorrect, corrupted, or does not correspond to the public key used by the IdP to encrypt the assertion.
fix
Verify that the `private_key` configured for the `ServiceProvider` is the correct private key corresponding to the certificate used by the IdP for encryption. Ensure the PEM format is correct and there are no extra characters.
Upgrade
Version history
4.0.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
28 hits · last 30 days
node
26
OpenAI (training)
1
Resources
githubhttps://github.com/Clever/saml2 ↗
packagehttps://www.npmjs.com/package/saml2-js ↗
homepagehttps://saml2-js.com ↗