{"id":18936,"library":"wsfed","title":"node-wsfed","description":"WSFed server middleware (SAML) for Express.js to generate WS-Federation endpoints. Current stable version: 8.0.0 (released March 2026). Maintained by Auth0, with regular releases. Key differentiators: supports SAML assertions, JWT tokens, encryption, and metadata endpoint generation; designed to work with external user authentication. Alternatives include passport-saml or adal-node for WS-Federation.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/auth0/node-wsfed","tags":["javascript","wsfed","saml","auth"],"install":[{"cmd":"npm install wsfed","lang":"bash","label":"npm"},{"cmd":"yarn add wsfed","lang":"bash","label":"yarn"},{"cmd":"pnpm add wsfed","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"middleware designed for Express.js","package":"express","optional":true}],"imports":[{"note":"ESM-only since v8; require() will fail. Use dynamic import if needed.","wrong":"const wsfed = require('wsfed')","symbol":"default","correct":"import wsfed from 'wsfed'"},{"note":"Named export for auth middleware.","wrong":"const { auth } = require('wsfed')","symbol":"wsfed.auth","correct":"import { auth } from 'wsfed'"},{"note":"Named export for metadata endpoint.","wrong":"const { metadata } = require('wsfed')","symbol":"wsfed.metadata","correct":"import { metadata } from 'wsfed'"}],"quickstart":{"code":"import express from 'express';\nimport wsfed from 'wsfed';\nimport fs from 'fs';\nimport path from 'path';\n\nconst app = express();\n\napp.get('/wsfed', wsfed.auth({\n  issuer: 'the-issuer',\n  cert: fs.readFileSync(path.join(__dirname, 'cert.pem')),\n  key: fs.readFileSync(path.join(__dirname, 'key.pem')),\n  getPostURL: function (wtrealm, wreply, req, callback) {\n    // return the URL to post the result response to\n    callback(null, 'http://someurl.com');\n  }\n}));\n\napp.get('/wsfed/FederationMetadata/2007-06/FederationMetadata.xml', wsfed.metadata({\n  issuer:   'the-issuer',\n  cert:     fs.readFileSync(path.join(__dirname, 'cert.pem')),\n}));\n\napp.listen(3000, () => console.log('WSFed server listening on port 3000'));","lang":"typescript","description":"Sets up Express WSFed middleware for auth and metadata endpoints using PEM keys."},"warnings":[{"fix":"Explicitly set encryptionAlgorithm option to your desired algorithm if needed.","message":"Since v8.0.0, encryption algorithm default changed to 'http://www.w3.org/2009/xmlenc11#aes256-gcm'. Old code relying on a different default may break.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Set disallowEncryptionWithInsecureAlgorithm: false if you must use insecure algorithms (not recommended).","message":"v8.0.0 introduced 'disallowEncryptionWithInsecureAlgorithm' defaulting to true. Assertions using insecure encryption algorithms will fail.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Avoid using these options; ensure proper key sizes and types.","message":"jwtAllowInsecureKeySizes and jwtAllowInvalidAsymmetricKeyTypes options are insecure and deprecated. They exist only for backward compatibility.","severity":"deprecated","affected_versions":">=7.0.0"},{"fix":"Always call the callback with two arguments: null and the URL string.","message":"The getPostURL callback expects (wtrealm, wreply, req, callback) -> callback(null, url). Returning a URL directly is incorrect.","severity":"gotcha","affected_versions":"*"},{"fix":"Read file contents as UTF-8 or default to string via fs.readFileSync(path, 'utf8').","message":"The cert and key options must be PEM strings, not file paths or buffers. Use fs.readFileSync to read the files into strings.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Install: npm install wsfed. If using CJS, use dynamic import: const wsfed = await import('wsfed');","cause":"Package not installed or ESM import in CJS project.","error":"Cannot find module 'wsfed'"},{"fix":"Ensure getPostURL function signature is (wtrealm, wreply, req, callback) and call callback(null, url).","cause":"The getPostURL callback is incorrectly defined; often due to using callbacks with async/await incorrectly.","error":"TypeError: cb is not a function"},{"fix":"Double-check file paths and use fs.readFileSync with 'utf8' encoding to get PEM string.","cause":"Cert or key file path is incorrect or file is not in PEM format.","error":"Error: Failed to load certificate / key"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}