Registry / auth-security / remix-auth-saml

remix-auth-saml

JSON →
library1.2.0jsnpmunverified

remix-auth-saml provides a SAML 2.0 authentication strategy for Remix Auth, enabling single sign-on (SSO) integration in Remix applications. This library abstracts the complexities of SAML authentication flows, including service provider (SP) and identity provider (IdP) interactions, metadata exchange, and assertion processing. The current stable version is 1.2.0, with releases occurring periodically, primarily for dependency updates and minor fixes as seen in recent changelogs. Key differentiators include its direct integration with the Remix Auth ecosystem, providing a familiar API for developers already using `remix-auth`, and its explicit support for both Node.js and Cloudflare runtimes, making it versatile for various deployment targets.

npm install remix-auth-saml
INSTALL
IMPORT
SIG · REMIX-AUTH-SAML
R
remix-auth-saml
auth-securityjavascriptv1.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 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();
Debug
Known issues
gotchaSAML configuration requires precise matching between the Service Provider (your Remix app) and the Identity Provider (IdP). Small mismatches in `authURL`, `callbackURL`, certificate formats, or signing/encryption preferences can lead to authentication failures that are difficult to debug.
fix
Carefully review all SAML configuration options with your IdP administrator. Use tools like SAML Tracer browser extensions to inspect SAML messages for discrepancies. Ensure URLs are exact and public/private keys are correctly generated and matched.
affects: >=1.0.0
gotchaA SAML XML validator is a mandatory dependency for `remix-auth-saml`, but it's not bundled. Forgetting to install one (e.g., `@authenio/samlify-node-xmllint`) will cause runtime errors when the strategy attempts to process SAML responses.
fix
Install a compatible XML validator package (e.g., `npm install @authenio/samlify-node-xmllint`) and pass it to the `SamlStrategy` constructor via the `validator` option.
affects: >=1.0.0
gotchaWhen deploying to environments with different hostnames or port numbers, the `authURL`, `callbackURL`, and `idpMetadataURL` configured in `SamlStrategy` must reflect the actual public-facing URLs. Hardcoding `localhost` will lead to issues in production.
fix
Use environment variables (e.g., `process.env.APP_BASE_URL`) to dynamically configure these URLs, ensuring they match the deployed environment's address.
affects: >=1.0.0
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.
fix
Install 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')`.
fix
Ensure `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.
Upgrade
Version history
1.2.0latest on npm
Audit
Dependencies
@remix-run/server-runtimerequiredRequired peer dependency for Remix application runtime services, essential for session management and server-side utilities.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
remix-auth-saml — npm install remix-auth-saml · libregistry