SAML Test Identity Provider

Common errors

• Missing required option: cert

  cause The `cert` option (path to the IdP's public certificate) was not provided or the file could not be read. Similarly, `key`, `acsUrl`, and `issuer` are also required.
  fix Provide all mandatory options to `runServer` or as command-line arguments. For `cert` and `key`, ensure the certificate files exist at the specified paths and are readable by the Node.js process. For `acsUrl` and `issuer`, provide valid URI strings.

Warnings

• gotcha This library is explicitly designed for testing purposes only and is **not intended for use with production systems.** Deploying `saml-idp` in a production environment could lead to severe security vulnerabilities due to its simplified security model.
  Fix: Do not use `saml-idp` outside of development and testing environments. For production, use a battle-tested and security-hardened Identity Provider solution.
• gotcha A self-signed certificate key pair (`idp-private-key.pem` and `idp-public-cert.pem`) is required for the IdP to function, but these files are not automatically generated by the package installation.
  Fix: Generate the key pair using OpenSSL with the command: `openssl req -x509 -new -newkey rsa:2048 -nodes -subj '/C=US/ST=California/L=San Francisco/O=JankyCo/CN=Test Identity Provider' -keyout idp-private-key.pem -out idp-public-cert.pem -days 7300`. Ensure these files are accessible to the `saml-idp` process or specify custom paths via the `key` and `cert` options.
• gotcha The private key generated for the IdP signing certificate (`idp-private-key.pem`) should be unique to your test IdP instance and must never be shared or exposed.
  Fix: Ensure generated private keys are securely stored and used only within isolated test environments. Regenerate keys immediately if compromise is suspected.

Install

• npm install saml-idp npm
• yarn add saml-idp yarn
• pnpm add saml-idp pnpm

Imports

• runServer
  wrong:

  import { runServer } from 'saml-idp';

  correct:

  const { runServer } = require('saml-idp');

  The package is primarily designed for CommonJS environments. Direct ESM imports might require specific Node.js configuration or bundler setup.
• runServer (alternative CJS)

  const samlIdp = require('saml-idp');
  samlIdp.runServer(...);

  CommonJS named export access via direct property.

Quickstart

This quickstart demonstrates how to programmatically start the `saml-idp` server, configure required SAML parameters, and define custom user attributes (claims) for assertions. It also highlights the necessity of pre-generating certificate files.

const { runServer } = require('saml-idp');
const path = require('path');
const fs = require('fs');

// Ensure you have generated these files with openssl:
// openssl req -x509 -new -newkey rsa:2048 -nodes -subj '/C=US/ST=California/L=San Francisco/O=JankyCo/CN=Test Identity Provider' -keyout idp-private-key.pem -out idp-public-cert.pem -days 7300

const privateKeyPath = path.resolve(__dirname, 'idp-private-key.pem');
const publicKeyPath = path.resolve(__dirname, 'idp-public-cert.pem');

// Basic example for starting an IdP server
runServer({
  acsUrl: process.env.SP_ACS_URL ?? 'https://sp.example.com/auth/saml20/assertion-consumer',
  audience: process.env.SP_AUDIENCE ?? 'https://sp.example.com/auth/saml20/metadata',
  issuer: process.env.IDP_ISSUER ?? 'urn:example:test-idp',
  key: fs.readFileSync(privateKeyPath, 'utf-8'),
  cert: fs.readFileSync(publicKeyPath, 'utf-8'),
  host: 'localhost',
  port: 7000,
  config: {
    user: {
      email: 'saml.jackson@example.com',
      firstName: 'Saml',
      lastName: 'Jackson',
      userType: 'Admin'
    },
    metadata: [
      { id: 'email', optional: false, displayName: 'E-Mail Address', description: 'The e-mail address', multiValue: false },
      { id: 'firstName', optional: false, displayName: 'First Name', description: 'The first name', multiValue: false },
      { id: 'lastName', optional: false, displayName: 'Last Name', description: 'The last name', multiValue: false },
      { id: 'userType', optional: true, displayName: 'User Type', description: 'The type of user', options: ['Admin', 'Editor', 'Commenter'] }
    ]
  }
});

console.log('SAML IdP test server running at http://localhost:7000');