SAML/ADFS node.js implementation guide?

I recently went through the same thought process: having never heard of SAML, I needed to enable a web application to authenticate via SAML with OneLogin as the identity provider (instead of Active Directory).

During implementation, I made heavy use of OneLogin's documentation and the passport-saml library, both of which I recommend, though I'm not affiliated with either.

What I came to realize was that the confusion was three-fold:

(1) how SAML works,

(2) how the passport-saml library works in Node, and

(3) how to configure the identity provider (OneLogin, Active Directory, or otherwise). What follows is my attempt at an "explain-like-I'm-five" explanation.

SAML

Security Assertion Markup Language (SAML) is an XML standard that allows users to log in based on their browser session. There's a lot to it, but basically, it enables a simpler authentication process. A user can click a button rather than submit a form with username and password.

The way SAML works is a little more involved. I found this overview from OneLogin and the accompanying diagram helpful:

The diagram represents the following process:

1. User clicks a button to authenticate for a given application (sometimes called service provider) using SAML. A request is made (to Node or otherwise) to build a SAML authorization request.
2. An authorization request is constructed. This authorization request is XML (see more on OneLogin), encoded and/or encrypted, and appended to a URL as a query param. Node redirects the browser to this URL (something like https://domain.onelogin.com/trust/saml2/http-post/sso/123456?SAMLRequest=...encodedXML...).
3. OneLogin, as identity provider, determines from the browser session whether the user is already logged in. If not, the user is prompted with OneLogin's login form. If so, the browser POSTs a SAML response back to the application (service provider). This SAML response (again XML) includes certain properties about the user, like NameID.
4. Back in Node, the application verifies the SAML response and completes authentication.

Node and passport-saml

Passport.js is authentication middleware for Node. It requires a strategy, which could be something like passport-local or, in our case, passport-saml.

As the passport-local strategy enables Passport authentication using username/password, the passport-saml strategy enables Passport authentication using the browser session and configurable identity provider values.

While passport-saml served my purposes really well, its docs were difficult to reason through. The configuration example doesn't work due since the OpenIdp identity provider is inactive and there are lots of configurable parameters.

The main one I cared about: entryPoint and path (or callbackURL). I only needed these two, which do the following:

• entryPoint is the URL to redirect to with the authorization request (see #2 above).
• path/callbackURL set the URL/route in Node for the SAML response to be POSTed to (see #3 above).

There's a ton of other parameters that are important and valuable, but it's possible to configure SAML SSO using just these two.

Identity Provider configuration

Finally, the identity provider itself needs to be configured so that, given a SAML authorization request, it knows where to send the SAML response. In the case of OneLogin, that means setting an ACS (Consumer) URL and an ACS (Consumer) URL Validator, both of which should match the path/callbackURL configured for passport-saml.

Other things can be configured (to support logout and other features), but this is the bare minimum to authenticate.

---

Summary

There were two parts to the original question: (1) how to implement SAML/ADFS integration and (2) high-level SAML node.js implementation guide. This answer addresses the second.

As for specifically integrating with Active Directory, I recommend passport-saml's docs on ADFS, keeping in mind that there's two parts: configuring passport-saml to use an ADFS identity provider AND configuring your ADFS server to respond back to Node.

I could be wrong here but I believe it comes from the ADFS servers XML found at https://servername/FederationMetadata/2007-06/FederationMetadata.xml.

Pull out the X509Certificate. I have the same issues going on and I'm going to try that next.

As for the first part of your question, the certificate comes from the provider. Please have a look at the passport-saml documentation.

Simply pull out the Identity Provider's public signing certificate (X.509) and make sure to format it to the PEM encoding. The correctly formatted PEM-encoded certificate will begin with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.