Self-hosted installation

Install and self-host SAML Shield’s open source library.

Introduction

SAML Shield’s open-source Node.js library lets you validate SAML responses locally, directly within your authentication flow. It gives you full control over how and where validation happens ideal for security-conscious teams who prefer self-hosted solutions or want to embed protection into internal platforms without relying on external services. Here's a diagram of how your authentication flow will look after integrating SAML Shield:

Pre-req:

Before you begin, you’ll need:

• A node application that acts as a Service Provider and validates SAML assertions. The OSS version only supports Node.js. Please checkout the Managed SAML Shield if you need other language support.

Installation

1. Install the SDK

Install the SAML Shield SDK from npm:

npm install @stytch/samlshield

2. Validate a SAML response

Validate the SAML response in your application by call the library:

import { validateSAMLResponse } from "@stytch/samlshield";

// Basic usage - throws errors on validation failure
try {
  await validateSAMLResponse({
      response_xml: req.body.SAMLResponse, // Base64 encoded SAML Response
  });
  console.log('SAML response is valid!');
} catch (error) {
  console.error('SAML validation failed:', error.message);
}

Testing Your Integration

Test if your SAML Shield integration is working by running a standard and malicious SAML assertion:

Run a valid SAML assertion

First, verify that your integration handles a valid SAML assertion end-to-end. Use your existing identity provider (e.g., Okta, Entra ID, or Google Workspace) and log in through your connected service (SP). If the assertion is valid and your SAML Shield integration is functioning, the flow should succeed without error.

Run a malicious SAML assertion

Try submitting an intentionally malformed or non-compliant response. For example, run this command:

EXAMPLE_SAML_RESPONSE="$(curl https://samlshield.com/examples/unsigned_saml_response.txt | base64)"
# Replace the SAML_CALLBACK_ENDPOINT with your SAML ACS endpoint
SAML_CALLBACK_ENDPOINT="https://samlshield.com/api/examples/callback" 
curl -X POST $SAML_CALLBACK_ENDPOINT \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode "SAMLResponse=$EXAMPLE_SAML_RESPONSE"

Next steps

If both tests behave as expected, your integration is correctly enforcing SAML Shield’s security guarantees and is ready to catch a broad class of SAML-based attacks. To stay protected as new threats emerge, subscribe to SAML Shield release updates to stay informed about newly added validation rules and improvements.

From here, it’s also important to enforce critical checks such as strict Audience and Issuer validation to prevent lateral movement or misissued assertion abuse that are outside of the scope of SAML Shield. For a clear breakdown of what SAML Shield protects against—and what remains your application’s responsibility, please refer to our security coverage page.