Why We Wrote Yet Another SAML Library

If there’s one thing the NPM community is famous for, its fragmentation. For many engineering problems, we’ve shot right past “there’s a module for that!” to “how do I choose one of these five similar packages?” — so it might seem counter-intuitive to author a new module in a well-established space like single sign on. After all, the current players are actually pretty solid. Saml20 is a very robust library, but only supports the service provider half of SSO handshakes. Saml only supports identity providers issuing SAML 1.1 tokens. Passport-saml is very secure, but is really only targeted at apps built with Passport. Saml2-js is a by far the most comprehensive solution currently on NPM — and its framework-agnostic protocol implementation is very versatile — but we wanted to support multiple SPs and IDPs with a wider range of signing, encryption, and protocol binding options. To that end, we wrote saml-protocol.

SAML-Protocol is a SAML2 protocol implementation inspired by Spring-Security-SAML, an enterprise-grade Java implementation. By enterprise-grade, I mean “really, really configurable” as opposed to “vendor-locked, XML-based, and slow”. To emulate the features we liked from this library, we chose to include support for both service and identity providers to allow users to test their integrations themselves. Our library supports both the HTTP-Post and HTTP-Redirect bindings, and can be configured to handle a variety of signing and encryption cases on a per-integration basis. Here are a few of the use cases that might make saml-protocol a good fit.

• Do you currently have to care about whether your IDP signs their payloads before or after encryption? We’ve got it covered.
• Need to handle multiple IDPs using one assertion endpoint, preventing you from knowing which IDP is associated with a response before payload inspection? We handle IDP resolution as a callback accepting an entity ID.
• Tired of manually configuring partner endpoints and certs? We handle metadata generation and ingestion for both IDPs and SPs, so you can pass the XML artifacts back and forth without having to manually inspect them.
• Need to handle signing certificate rotation? Our configs take an array of credentials.

We hope that by open-sourcing this module, we can provide the NPM community with a greater level of SSO support and fewer implementation headaches.