node-wsfed

8.0.0 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Cannot find module 'wsfed' ↓

cause Package not installed or ESM import in CJS project.

fix

Install: npm install wsfed. If using CJS, use dynamic import: const wsfed = await import('wsfed');

error TypeError: cb is not a function ↓

cause The getPostURL callback is incorrectly defined; often due to using callbacks with async/await incorrectly.

fix

Ensure getPostURL function signature is (wtrealm, wreply, req, callback) and call callback(null, url).

error Error: Failed to load certificate / key ↓

cause Cert or key file path is incorrect or file is not in PEM format.

fix

Double-check file paths and use fs.readFileSync with 'utf8' encoding to get PEM string.

Warnings

breaking 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. ↓

fix Explicitly set encryptionAlgorithm option to your desired algorithm if needed.

breaking v8.0.0 introduced 'disallowEncryptionWithInsecureAlgorithm' defaulting to true. Assertions using insecure encryption algorithms will fail. ↓

fix Set disallowEncryptionWithInsecureAlgorithm: false if you must use insecure algorithms (not recommended).

deprecated jwtAllowInsecureKeySizes and jwtAllowInvalidAsymmetricKeyTypes options are insecure and deprecated. They exist only for backward compatibility. ↓

fix Avoid using these options; ensure proper key sizes and types.

gotcha The getPostURL callback expects (wtrealm, wreply, req, callback) -> callback(null, url). Returning a URL directly is incorrect. ↓

fix Always call the callback with two arguments: null and the URL string.

gotcha The cert and key options must be PEM strings, not file paths or buffers. Use fs.readFileSync to read the files into strings. ↓

fix Read file contents as UTF-8 or default to string via fs.readFileSync(path, 'utf8').

Install

npm install wsfed

yarn add wsfed

pnpm add wsfed

Imports

default
wrong
```
const wsfed = require('wsfed')
```
correct
```
import wsfed from 'wsfed'
```
ESM-only since v8; require() will fail. Use dynamic import if needed.

wsfed.auth

wrong

const { auth } = require('wsfed')

correct

import { auth } from 'wsfed'

Named export for auth middleware.

wsfed.metadata

wrong

const { metadata } = require('wsfed')

correct

import { metadata } from 'wsfed'

Named export for metadata endpoint.

Quickstart

Sets up Express WSFed middleware for auth and metadata endpoints using PEM keys.

import express from 'express';
import wsfed from 'wsfed';
import fs from 'fs';
import path from 'path';

const app = express();

app.get('/wsfed', wsfed.auth({
  issuer: 'the-issuer',
  cert: fs.readFileSync(path.join(__dirname, 'cert.pem')),
  key: fs.readFileSync(path.join(__dirname, 'key.pem')),
  getPostURL: function (wtrealm, wreply, req, callback) {
    // return the URL to post the result response to
    callback(null, 'http://someurl.com');
  }
}));

app.get('/wsfed/FederationMetadata/2007-06/FederationMetadata.xml', wsfed.metadata({
  issuer:   'the-issuer',
  cert:     fs.readFileSync(path.join(__dirname, 'cert.pem')),
}));

app.listen(3000, () => console.log('WSFed server listening on port 3000'));