{"id":13977,"library":"saml2-js","title":"SAML 2.0 Node.js Helpers","description":"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`.","status":"maintenance","version":"4.0.4","language":"javascript","source_language":"en","source_url":"git://github.com/Clever/saml2","tags":["javascript","saml","node"],"install":[{"cmd":"npm install saml2-js","lang":"bash","label":"npm"},{"cmd":"yarn add saml2-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add saml2-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses CommonJS `require` syntax. Direct ESM imports are not officially supported or documented for main exports.","wrong":"import saml2 from 'saml2-js';","symbol":"saml2","correct":"const saml2 = require('saml2-js');"},{"note":"ServiceProvider is a named export from the main `saml2` object, not a top-level import for CommonJS.","wrong":"import { ServiceProvider } from 'saml2-js';","symbol":"ServiceProvider","correct":"const { ServiceProvider } = saml2;"},{"note":"IdentityProvider is a named export from the main `saml2` object, not a top-level import for CommonJS.","wrong":"import { IdentityProvider } from 'saml2-js';","symbol":"IdentityProvider","correct":"const { IdentityProvider } = saml2;"}],"quickstart":{"code":"const saml2 = require('saml2-js');\nconst fs = require('fs');\nconst path = require('path');\n\n// In a real application, these would be loaded securely (e.g., from environment variables).\n// For demonstration, using dummy values and assuming keys/certs exist.\nconst spPrivateKey = process.env.SP_PRIVATE_KEY ?? '-----BEGIN RSA PRIVATE KEY-----\\n...your_private_key...\\n-----END RSA PRIVATE KEY-----';\nconst spCertificate = process.env.SP_CERTIFICATE ?? '-----BEGIN CERTIFICATE-----\\n...your_certificate...\\n-----END CERTIFICATE-----';\nconst idpCertificate = process.env.IDP_CERTIFICATE ?? '-----BEGIN CERTIFICATE-----\\n...idp_certificate...\\n-----END CERTIFICATE-----';\n\n// Service Provider (SP) options\nconst spOptions = {\n  entity_id: \"https://sp.example.com/metadata\",\n  private_key: spPrivateKey,\n  certificate: spCertificate,\n  assert_endpoint: \"https://sp.example.com/sso/assert\"\n};\n\n// Identity Provider (IdP) options (minimal for login request)\nconst idpOptions = {\n  entity_id: \"https://idp.example.com/saml/metadata\",\n  sso_login_url: \"https://idp.example.com/saml/sso\",\n  certificates: [idpCertificate]\n};\n\n// Instantiate SP and IdP\nconst sp = new saml2.ServiceProvider(spOptions);\nconst idp = new saml2.IdentityProvider(idpOptions);\n\n// Generate a SAML login request URL (for SP-initiated SSO)\nsp.create_login_request_url(idp, {}, (err, loginUrl, requestId) => {\n  if (err) {\n    console.error(\"Error creating login request URL:\", err);\n    return;\n  }\n  console.log(\"SAML Login Request URL:\\n\", loginUrl);\n  console.log(\"Request ID:\", requestId);\n  // In a web application, you would redirect the user to this loginUrl.\n  // e.g., res.redirect(loginUrl);\n});\n\n// Example of generating SP metadata (to provide to the IdP)\nsp.create_metadata((err, metadata) => {\n  if (err) {\n    console.error(\"Error creating SP metadata:\", err);\n    return;\n  }\n  console.log(\"\\nService Provider Metadata:\\n\", metadata);\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Developers requiring new SAML features or extensive support should consider alternative, actively developed SAML libraries for Node.js.","message":"The `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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"Setting `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).","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"Incorrect 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"Securely 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If Identity Provider functionality is required, select a different SAML library specifically designed for IdP implementations.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.0':2,19 '4.0.4':59 'abstract':30 'act':23,51 'address':69 'allow':33 'applic':34 'assert':131 'authent':42 'authn':141 'author':44 'away':31 'behavior':138 'bug':70 'cadenc':85 'clear':104 'complex':32 'configur':107 'constructor':117 'critic':91 'cryptograph':129 'current':47 'develop':78 'differenti':94 'driven':89 'endpoint':132 'entiti':127 'featur':77 'fix':92 'focus':66,97 'forc':140 'format':144 'function':101 'helper':4 'id':128 'ident':38,54 'identityprovid':121 'idp':40 'implement':15 'includ':95 'integr':36 'issu':74 'javascript':145 'js':7 'key':93,130 'librari':46 'like':139 'mainten':64 'manag':110,126 'mode':65 'modul':11 'nameid':143 'node':147 'node.js':3,10 'object':122 'offer':116 'option':108,124 'primarili':67 'project':61 'protocol':20 'provid':27,39,55 'rather':75 'regular':83 'releas':84 'report':71 'request':112 'respons':114 'saml':1,18,111,136,146 'saml-specif':135 'saml2':6 'saml2-js':5 'secur':73 'servic':26 'serviceprovid':119 'set':105 'simplifi':13 'sole':98 'sp':28,100 'specif':21,137 'state':82 'support':50 'updat':87 'various':134 'version':58","created_at":"2026-04-20T01:57:18.192292+00:00","updated_at":"2026-04-20T01:57:18.192292+00:00","problems":[{"fix":"Use `const saml2 = require('saml2-js');` and then `new saml2.ServiceProvider(...)`.","cause":"Attempting to destructure or import `ServiceProvider` directly using ESM syntax or incorrect CommonJS requiring.","error":"TypeError: saml2.ServiceProvider is not a constructor"},{"fix":"Provide a unique identifier string for `entity_id` in the `ServiceProvider` options object.","cause":"Missing the mandatory `entity_id` property in the `ServiceProvider` constructor options.","error":"Error: Required option 'entity_id' not provided for ServiceProvider"},{"fix":"Update the `audience` option in `ServiceProvider` to precisely match one of the valid audience values provided by the Identity Provider.","cause":"The `audience` configured in the `ServiceProvider` does not match any of the `<Audience>` values within the SAML assertion received from the IdP.","error":"Error: SAML Assertion Audience Restriction mismatch. Expected [expected_audience], received [received_audience]."},{"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.","cause":"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.","error":"Error: SAML Assertion NotBefore condition invalid. Current time: [timestamp], NotBefore: [notbefore_timestamp]"},{"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.","cause":"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.","error":"Error: Decryption failed for SAML assertion. Bad padding or invalid key."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://saml2-js.com","github":"https://github.com/Clever/saml2","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/saml2-js","openapi_spec":null,"status_page":null,"smithery":null,"categories":["auth-security","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}