Stytch-hosted Proxy installation

Run SAML Shield as a proxy for applications you don’t control, such as 3rd-party platforms or multi-tenant environments.

Integration Overview

Here's a diagram of how your authentication flow will look after integrating SAML Shield:

SAML Shield OSS Integration Flow

Pick a proxy

SAML Shield has the following integrations out of the box. Choose your preferred integration below to see implementation details:

If you don’t see your preferred proxy listed, don’t worry, you can still query SAML Shield via our Managed HTTP API using the configuration of your proxy system.

Have a proxy you’d like us to support? Contact Support we’d love to hear from you.

Installation

This NGINX setup uses OpenResty and a Lua access handler to enforce SAML Shield validation on the SAML ACS endpoint. Requests to this endpoint are intercepted by NGINX and forwarded to the SAML Shield API for validation. The Lua script defines which requests require validation and configures NGINX to call the external service, passing along selected headers, the request body, and an authorization token. If the external check passes, the request is proxied to the application.

1. Create a Lua Auth Proxy Script

Add the following Lua script to your NGINX installation. This script runs inside your NGINX configuration using OpenResty and forwards incoming requests to the SAML Shield API for validation before proxying them to your backend.

local http = require "resty.http"

-- Define the SAML Shield API endpoint and token
local samlshield_url = "https://api.samlshield.com/v1/saml/validate"

# retrieved from SAML Shield Dashboard
local bearer_token = "Bearer $PUBLIC_TOKEN"

-- Only check on the ACS endpoint
if ngx.var.request_uri == "/saml/callback" then
local httpc = http.new()
httpc:set_timeout(3000) -- 3 seconds timeout

  -- Read request body
  ngx.req.read_body()
  local body = ngx.req.get_body_data()

  local res, err = httpc:request_uri(samlshield_url, {
      method = "POST",
      body = body,
      headers = {
          ["Authorization"] = bearer_token,
          ["Content-Type"] = ngx.req.get_headers(),
      }
  })

  if not res then
      ngx.log(ngx.ERR, "Failed to connect to SAML Shield: ", err)
      return ngx.exit(ngx.HTTP_FORBIDDEN)
  end

  if res.status ~= 200 then
      ngx.log(ngx.WARN, "SAML Shield rejected request with status: ", res.status)
      return ngx.exit(ngx.HTTP_FORBIDDEN)
  end

end

2. Add to your NGINX config

Moidfy your NGINX config to use the Lua script for the ACS endpoint.

http {
server { # other server configurations...
  location /saml/callback { # Your app's ACS endpoint
      access_by_lua_file /etc/nginx/lua/saml_auth.lua;
      proxy_pass http://backend_upstream;
  }
}
}

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.