Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SamlStrategy
✓ import { SamlStrategy } from 'remix-auth-saml';
✗ const SamlStrategy = require('remix-auth-saml').SamlStrategy;
remix-auth-saml is primarily designed for ESM environments, aligning with Remix's architecture. While CJS might work via transpilation, direct require() is discouraged for type safety and modern tooling.
metadata
✓ import { metadata } from 'remix-auth-saml';
✗ import metadata from 'remix-auth-saml';
The `metadata` function is a named export from the SamlStrategy instance, not a direct export from the package. The example shows `let metadata = samlStrategy.metadata();` which is the correct usage after instantiating the strategy.
Authenticator
✓ import { Authenticator } from 'remix-auth';
While not directly from `remix-auth-saml`, `Authenticator` from `remix-auth` is fundamental for using this strategy. It's crucial to understand it's a separate peer dependency.
This quickstart demonstrates the core setup for `remix-auth-saml`, including initializing `Authenticator`, configuring `SamlStrategy` with essential SAML parameters, and providing a `verify` callback to process user data post-authentication. It also shows how to expose the Service Provider (SP) metadata for your Identity Provider (IdP).
import { Authenticator } from "remix-auth";
import { sessionStorage } from "~/services/session.server"; // Assuming a session storage setup
import { SamlStrategy } from "remix-auth-saml";
import * as validator from "@authenio/samlify-node-xmllint"; // Or another SAML XML validator
// Create an Authenticator instance
export let authenticator = new Authenticator<any>(sessionStorage);
// Initialize the SAML strategy
let samlStrategy = new SamlStrategy(
{
validator,
authURL: "http://localhost:3000/auth/saml",
callbackURL: "http://localhost:3000/auth/saml/callback",
idpMetadataURL: "http://localhost:7000/metadata", // URL to your Identity Provider's metadata
spAuthnRequestSigned: false,
spWantAssertionSigned: false,
spWantMessageSigned: false,
spWantLogoutRequestSigned: false,
spWantLogoutResponseSigned: false,
spIsAssertionEncrypted: false,
// Optional: Specify private keys and certificates for signing/encryption
// privateKey: "./path/to/sp-private-key.pem",
// signingCert: "./path/to/sp-public-cert.pem"
},
async ({ extract, data }) => {
// This verify callback runs after successful SAML authentication
// 'extract' contains parsed user profile data from the SAML assertion
// 'data' is the raw IdP response, useful for backend verification or decryption
console.log("User profile extracted:", extract);
console.log("Raw IdP response data:", data);
// Here, you would typically find or create a user in your database
// based on 'extract' data and return the user object.
// Example: const user = await userService.findOrCreate(extract);
// return user;
// For this example, we'll just return a placeholder
return { id: extract.nameID, email: extract.attributes['urn:oid:0.9.2342.19200300.100.1.3'] };
}
);
// Register the strategy with the Authenticator
authenticator.use(samlStrategy, "saml");
// Export SP metadata for the IdP
export let spMetadata = samlStrategy.metadata();
Errors
Common errors & fixes
Error: Missing SAML validator. Please install a validator (e.g., @authenio/samlify-node-xmllint) and pass it into the strategy constructor.
The `validator` option was not provided or was null in the `SamlStrategy` constructor, which is a required dependency for SAML XML parsing and validation.
fixInstall a SAML XML validator like `@authenio/samlify-node-xmllint` (`npm i @authenio/samlify-node-xmllint`) and pass it to the `SamlStrategy` options: `new SamlStrategy({ validator: require('@authenio/samlify-node-xmllint'), ... })`. TypeError: Cannot read properties of undefined (reading 'authenticate')
The `authenticator` instance from `remix-auth` was not correctly initialized or exported, or the SAML strategy was not registered with it using `authenticator.use(samlStrategy, 'saml')`.
fixEnsure `authenticator` is correctly initialized with session storage and exported from `auth.server.ts`. Verify that `authenticator.use(samlStrategy, 'saml')` is called before attempting to use the 'saml' strategy.
Audit
Dependencies
@remix-run/server-runtimerequiredRequired peer dependency for Remix application runtime services, essential for session management and server-side utilities.