samlesa

v4.9.0

Published

a day ago

High-level API for Single Sign On (SAML 2.0) baseed on samlify

0High
0Medium
0Low

veclea

nodejs saml2 sso slo metadata

samlify ·

High-level API for Single Sign On (SAML 2.0) based on samlify

English Version | 中文版本

🔄 This Repository

This is an improved fork of samlify by tngan.

Key Improvements

📦 ESModule Support: Converted from CommonJS to ESModule
✅ Enhanced Encryption: Replaced @authenio/xml-encryption with xml-encryption, added support for SHA-256/512 encryption key OAEP digest methods
✅ Updated Dependencies: Upgraded @xmldom/xmldom to the latest version
🛠️ Fixed Encrypted Assertion: Improved encrypted assertion signature verification with EncryptedAssertion field extraction
📦 Default AttributeConsumingService: Added default AttributeConsumingService element generation for ServiceProvider
📦 Artifact Binding: Added partial Artifact binding support
🔒 Security Upgrades: Default signature algorithm upgraded to SHA-256, default encryption to AES_256_GCM
🧪 XML Validation: Built-in XML XSD validator
🐛 Bug Fixes: Improved HTTP-Redirect binding handling without DEFLATE compression
🔓 Auto Detection: Automatic detection of encrypted assertions without explicit flags
✅ Security Tested: Tested against Burp SAML Raider (XSW and XXE attacks)
⚡ Faster Testing: Migrated tests to Vitest

📖 Documentation

Full documentation is available at https://samlify.js.org.

Quick Links

🚀 Installation

npm install samlesa

📦 Supported Algorithms

Signature Algorithms

| Algorithm | URI | Security Level | Recommendation | |-----------|-----|----------------|----------------| | RSA-SHA256 | http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 | ✅ High | ⭐ Recommended | | RSA-SHA384 | http://www.w3.org/2001/04/xmldsig-more#rsa-sha384 | ✅ High | ✅ Supported | | RSA-SHA512 | http://www.w3.org/2001/04/xmldsig-more#rsa-sha512 | ✅ High | ✅ Supported | | RSA-PSS-SHA256 | http://www.w3.org/2007/05/xmldsig-more#rsa-pss-sha256 | ✅✅ Very High | ✅ Supported | | ECDSA-SHA256 | http://www.w3.org/2007/05/xmldsig-more#ecdsa-sha256 | ✅ High | ✅ Supported | | ECDSA-SHA384 | http://www.w3.org/2007/05/xmldsig-more#ecdsa-sha384 | ✅ High | ✅ Supported | | ECDSA-SHA512 | http://www.w3.org/2007/05/xmldsig-more#ecdsa-sha512 | ✅ High | ✅ Supported | | EdDSA-Ed25519 | http://www.w3.org/2007/05/xmldsig-more#eddsa-ed25519 | ✅✅ Very High | ✅ Supported | | EdDSA-Ed448 | http://www.w3.org/2021/04/xmldsig-more#eddsa-ed448 | ✅✅ Very High | ✅ Supported | | ~~RSA-SHA1~~ | http://www.w3.org/2000/09/xmldsig#rsa-sha1 | ❌ Low | ⚠️ Deprecated |

Encryption Algorithms (Data)

| Algorithm | URI | Mode | Recommendation | |-----------|-----|------|----------------| | AES-256-GCM | http://www.w3.org/2009/xmlenc11#aes256-gcm | GCM | ⭐ Recommended | | AES-128-GCM | http://www.w3.org/2009/xmlenc11#aes128-gcm | GCM | ✅ Supported | | AES-256-CBC | http://www.w3.org/2001/04/xmlenc#aes256-cbc | CBC | ✅ Supported | | AES-128-CBC | http://www.w3.org/2001/04/xmlenc#aes128-cbc | CBC | ✅ Supported | | AES-256-CTR | http://www.w3.org/2009/xmlenc11#aes256-ctr | CTR | ✅ Supported | | ~~TripleDES~~ | http://www.w3.org/2001/04/xmlenc#tripledes-cbc | CBC | ⚠️ Legacy Only |

Key Encryption Algorithms

| Algorithm | URI | Recommendation | |-----------|-----|----------------| | RSA-OAEP-MGF1P | http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p | ⭐ Recommended | | RSA-OAEP | http://www.w3.org/2009/xmlenc11#rsa-oaep | ✅ Supported | | AES-256-KW | http://www.w3.org/2001/04/xmlenc#kw-aes256 | ✅ Supported | | ~~RSA-1_5~~ | http://www.w3.org/2001/04/xmlenc#rsa-1_5 | ⚠️ Deprecated |

🔧 Usage

As a Service Provider (SP)

import { ServiceProvider, IdentityProvider } from 'samlesa';

// Initialize Service Provider
const sp = ServiceProvider({
  metadata: readFileSync('./sp-metadata.xml'),
  privateKey: readFileSync('./sp-key.pem'),
  signingCert: readFileSync('./sp-cert.cer'),
  isAssertionEncrypted: true,
  wantAssertionsSigned: true,
  wantMessageSigned: true,
});

// Initialize Identity Provider
const idp = IdentityProvider({
  metadata: readFileSync('./idp-metadata.xml'),
});

// Create login request
const { context: samlRequest, entityEndpoint } = sp.createLoginRequest(idp, 'redirect');

// Parse login response
const { extract } = await sp.parseLoginResponse(idp, 'redirect', {
  body: { SAMLResponse: responseFromIdp }
});

console.log('User:', extract.nameID);

As an Identity Provider (IdP)

import { IdentityProvider, ServiceProvider } from 'samlesa';

// Initialize Identity Provider
const idp = IdentityProvider({
  metadata: readFileSync('./idp-metadata.xml'),
  privateKey: readFileSync('./idp-key.pem'),
  signingCert: readFileSync('./idp-cert.cer'),
  isAssertionEncrypted: true,
  wantAuthnRequestsSigned: true,
});

// Initialize Service Provider
const sp = ServiceProvider({
  metadata: readFileSync('./sp-metadata.xml'),
});

// Parse login request
const { extract } = await idp.parseLoginRequest(sp, 'redirect', {
  query: { SAMLRequest: requestFromSp }
});

// Create login response
const { context: samlResponse } = await idp.createLoginResponse({
  sp,
  requestInfo: { extract },
  binding: 'post',
  user: { NameID: '[email protected]' },
});

Artifact Binding Support

import { ServiceProvider, IdentityProvider } from 'samlesa';

// Create front-channel artifact login request
const loginRequest = sp.createLoginRequest(idp, 'artifact');

// Parse ArtifactResolve request on the SP artifact resolution endpoint
const artifactResolve = await sp.parseArtifactResolveRequest(idp, soapXml);

// Create ArtifactResponse with the resolved SAML message
const artifactResponse = await sp.createArtifactResolveResponse(idp, {
  inResponseTo: artifactResolve.extract.request.id,
});

// Parse artifact-based login response from the ACS endpoint
const responseResult = await sp.parseLoginResponse(idp, 'artifact', request);

🔐 Security Features

✅ XXE Protection: Built-in XML External Entity attack prevention
✅ XSW Protection: Tested against XML Signature Wrapping attacks
✅ Schema Validation: XML Schema validation for all SAML messages
✅ Signature Verification: Comprehensive signature validation
✅ Time Validation: Configurable clock drift tolerance
✅ Destination Validation: Endpoint URL verification
✅ Certificate Validation: X.509 certificate validation

📁 Project Structure

samlify/
├── src/                      # Source code
│   ├── binding-artifact.ts   # Artifact binding implementation
│   ├── binding-post.ts       # POST binding implementation
│   ├── binding-redirect.ts   # Redirect binding implementation
│   ├── entity-idp.ts         # Identity Provider entity
│   ├── entity-sp.ts          # Service Provider entity
│   ├── libsaml.ts            # SAML utilities
│   └── schemaValidator.ts    # XML Schema validation
├── test/                     # Test files
│   ├── artifact.test.ts      # Artifact binding tests
│   ├── flow.test.ts          # Flow tests
│   └── key/                  # Test certificates
├── docs/                     # Documentation
└── scripts/                  # Utility scripts
    └── generate-certs.js     # Certificate generation

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Run artifact binding tests only
npm run test:artifact

# Fast test run (parallel)
npm run test:fast

🛠️ Development

# Install dependencies
npm install

# Build the project
npm run build

# Fast build (incremental)
npm run build:fast

# Generate test certificates (requires OpenSSL)
npm run generate-certs

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to:

Submit pull requests
Report issues
Provide integration examples with other frameworks
Improve documentation

📧 Support

Issues: GitHub Issues
Documentation: https://samlify.js.org
Email: [email protected]