DEV Community: WorkOS Developer Relations

Fun with SAML SSO Vulnerabilities and Footguns

WorkOS Developer Relations — Fri, 29 Jan 2021 21:06:25 +0000

If you’re here, you’ve likely been tasked with building SAML-based SSO as a requirement for an enterprise deal. If you’re just diving into the problem space of SSO / SAML, we’d first suggest checking out The Developer’s Guide to SSO. Otherwise, buckle up for a brief but titillating foray into why XML-based authentication is... challenging.

Why is SAML SSO so vulnerability-prone

The attack surface for SAML authentication is extensive, mostly due to the fact that SAML is XML-based. XML is a semantic-free meta-language - it’s hard to form, hard to read, and hard to parse. Combined with the high complexity of the SAML specification and the number of parties involved in establishing authentication, we get what often feels like a big ball of mud and all the accompanying implications. Be prepared to tackle a steep learning curve, lots of bugs, high maintenance costs, attack vectors galore, and an absurd spread of edge cases.

Most SAML SSO security vulnerabilities are introduced by Service Providers (SPs) improperly validating and processing SAML responses received from Identity Providers (IdPs). This happens because SAML SSO is typically not a core-value feature for an application, nor is the implementation common knowledge for most developers. Unknowns become even more unlikely to be identified and addressed when the pressure is on to just deliver something to unblock a high-value contract - as is oftentimes the case. However, to build SAML SSO safely and securely in-house requires significant buy-in and investment by teams - on the scale of months, representing hundreds of thousands of dollars in developer time.‍

If not done right, you expose your application and your customers to potentially huge security risks. To drive that home, here are just a few recently published SAML-related vulnerabilities:

January 27, 2020 - “... GitLab SAML integration had a validation issue that permitted an attacker to takeover another user's account.”
May 7, 2020 - “... an attacker could exploit this [SAML] vulnerability to bypass the authentication process and gain full administrative access to the system [IBM Data Risk Manager].”
June 19, 2020 - “An attacker could authenticate to a different user's [Mattermost] account via a crafted SAML response.”
June 29, 2020 - “... improper verification of signatures in PAN-OS SAML authentication enables an unauthenticated network-based attacker to access protected resources.”

It should be evident by now that oversights in SAML implementations are ubiquitous and problematic, even among experienced engineering teams.

So let’s dive into some of the more common security pitfalls developers building SAML-based SSO should be aware of, as well as cover a few suggested countermeasures. Just to be clear, this guide is by no means comprehensive and is meant to provide a starting point for SAML security considerations as well as some follow-on resources.

Brief anatomy of a SAML response

Let's say we're integrating our application with Okta via SAML. Below is an example of an XML document we might get when attempting to authenticate a user, containing a simplified but valid SAML response:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xs="http://www.w3.org/2001/XMLSchema" Destination="https://api.workos-test.com/auth/okta/callback" ID="id72697176167120131651975993" InResponseTo="_b464ac6d6621d7a1a814" IssueInstant="2019-11-27T02:45:30.657Z" Version="2.0">
  <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk1klancwHzz1SNi357</saml2:Issuer>
  <saml2p:Status xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
    <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </saml2p:Status>
  <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="id7269717616793800631152500" IssueInstant="2019-11-27T02:45:30.657Z" Version="2.0">
    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/exk1klancwHzz1SNi357</saml2:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
        <ds:Reference URI="#id7269717616793800631152500">
          <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
              <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs"/>
            </ds:Transform>
          </ds:Transforms>
          <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
          <ds:DigestValue>k+u/Rfv5sDoEJ9Zsk9DCNzBiWQ4aeJtVCk21SYIFupc=</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>TxG611vjAtZ/+F2QFtzcByyh7Hb5Dq928NC6a9FvsfT8r/VENRQ6iUfcZiQDImsCNbc58p8ftYRiKf0pFsGz4Y821c/POBqjaW7eL7J6c7EwBJcSRX6/xGbPd1jgvc4QVPfZuchdjJL6a2vAXPaFM3BDa2mpqp2/bd4VqkjAibvoygqNaI/TzTT5E28nSAez39Y+dzL16jlo4d/5T3g0gqLwsbD0w6KveyJXSQpjyuj1nel3R1w8SZITZmdNBwiPwbk04iE7zWbTNVkh9Dgo+xhhwSpqwBzq4KiCvYl7HhHCgjJVKCPh28V/2xANqZjTtgNB3lrnmz/MwnRn9H5Jsg==</ds:SignatureValue>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MIIDpDCCAoygAwIBAgIGAWz5LOgCMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi04Mzk3NDAxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMTkwOTAzMjIwODI1WhcNMjkwOTAzMjIwOTI1WjCBkjELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNVBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtODM5NzQwMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzCXtN0wgczIzU3nKnFb64XZPJB4m+JWX45lUDYoxOLJJKpv41pQ9Cq/SmYTj3EL23ZHA5W/xr9jSbfPYOYiJ6R3T8q6n2cLFWTXsS7axRxTC7Y6tUK+7RM5yydWxB17CsgSCmMGAqux2Z1HkA9JEJxVXCQDTVHww7tjO6bFrRXdWszJt5f6ESNIHfKgm+WXole61Kz3IW4vCQRdfAl7eoK4MBWERJN16j9N9NLpGaPBYs65oF1LQ7WWWZQ/8oYgLKszVvCkxdSBcpym39Ob/fdtdmKesVnxPLJjK/wB3WXVjbbUHqYy/ArkoK2FteYXLHzBmX89HOMuzofUYGbWbvQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBnVSSM4KJ0jO2R3AxF1IKY6orTbHXgl6/glZbSN0AT7Lpf7fduo7n1RnxToaKDQyRPumMPvPnHUvpkfg3BMjUGKFXJJYEc3pKoSrt/aoDsjPLxri+mjK8x0vasGbj7G+T2J6//TPVnGCGYJMRBG7LUfTCbFVVdIQy7agwE/rIzYSbQFaM1RoUAzIjWzkuDVmO6zWtVBUZgySO1dphPctgItPUmZEQUX+EiEK7Azg7wQmOiPv9Kwmj3SSxPmwCHxXScQLQdzicmaI6hMbOeCcFJSuxbGDc1xbJKd/WbLy1ZrDlcDPky8cJILFnZoh/y5+LX7YUEnIwxtE5Ohiwt78dz</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </ds:Signature>
    <saml2:Subject xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
      <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">demo@workos-okta.com</saml2:NameID>
      <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml2:SubjectConfirmationData InResponseTo="_b464ac6d6621d7a1a814" NotOnOrAfter="2019-11-27T02:50:30.657Z" Recipient="https://api.workos-test.com/auth/okta/callback"/>
      </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" NotBefore="2019-11-27T02:40:30.657Z" NotOnOrAfter="2019-11-27T02:50:30.657Z">
      <saml2:AudienceRestriction>
        <saml2:Audience>https://api.workos-test.com/auth/okta/callback</saml2:Audience>
      </saml2:AudienceRestriction>
    </saml2:Conditions>
  </saml2:Assertion>
</saml2p:Response>

Like we mentioned earlier, the SAML spec is complex and responses can get lengthy, so this example is comparatively quite terse. Keeping things to what you should know before we go into SAML vulnerabilities, let’s walk through what the response (<saml2p:Response>) is communicating:

Line 2 begins the SAML response, which has the unique ID id72697176167120131651975993 and is intended for consumption by the workos-test service provider’s Assertion Consumer Service (ACS) URL, i.e. the endpoint https://api.workos-test.com/auth/okta/callback.
Line 3 specifies the issuer (<saml2:Issuer>) and contains the unique URI (also referred to as EntityID) of the IdP that issued the response, in this case http://www.okta.com/exk1klancwHzz1SNi357.
Line 7 begins the assertion (<saml2:Assertion>) with the unique ID id7269717616793800631152500. An assertion is a package of information asserting the identity of a user, often containing additional user attributes like first / last name, email, ID, etc.
Line 8 specifies the issuer of the assertion itself, in this case also http://www.okta.com/exk1klancwHzz1SNi357.
Lines 9 - 30 contains the digital signature (<ds:Signature>) over the assertion, which should be validated to determine the authenticity of the assertion.
Lines 31 - 36 specify the subject (<saml2:Subject>) of the assertion, i.e. the authenticated principal / user corresponding to the unique identifier found in <saml2:NameID>, who in this case is demo@workos-okta.com.
Line 37 (<saml2:Conditions>) defines the window of time for which the assertion should considered valid, i.e. from NotBefore (inclusive) to NotOnOrAfter (exclusive).

For the purposes of readability, the SAML 2.0 XML snippets in the remainder of this blog will be simplified, use shorthand, and be stripped of nodes that would otherwise be required in reality but are not relevant to what’s being illustrated. We’ll use a mythical IssueTracker, ContractManager, and PayrollService as hypothetical SPs that have implemented SAML authentication, which you should think of as placeholders for your application or other SAML SSO-enabled apps.

Disable DTD processing

The first step in processing a SAML response is parsing the payload. Parsing and loading an XML document into memory is an inherently expensive set of operations, but can be unexpectedly costly due to a feature of XML that allows references to external or remote documents, i.e. Document Type Definitions (DTDs).

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Response [<!ENTITY ggwp SYSTEM "http://workos.com/¯\_(ツ)_/¯.xml">]>
<Response>&ggwp;</saml2p:Response>

When a DTD is encountered, parsers will try to fetch and load the referenced document as well. If the referenced document is large enough or results in infinitely looping references, your server can be slowed or even brought down trying to complete the process. The same holds true if the payload itself is very large, DTDs or not.

Two low-hanging mitigations you should implement to prevent buffer overflows are:

Limiting SAML payload size to < 1MB. 1MB is a generous upper limit and should be tuned down based on average received payload size.
Configuring your XML parser to never fetch remote files or try to load and parse DTDs. Some XML parsers do so by default, for example, Python’s xml.etree.ElementTree module.

XML processing, and thus by extension SAML response processing, is vulnerable to buffer overflow attacks from other scenarios described later on in this post. And unfortunately, protecting your application from a service outage is among the most mild of outcomes compared to the possibilities exploiting XML DTD allows - it is a dark and anxiety-inducing rabbit hole.

So, if you’re not writing your own XML parser (generally not suggested), it’s important to vet the XML parser(s) your application and its dependencies use - ensure they handle other exploits like Billion Laughs and Zip Bombs.

Validate the SAML response schema first

The primary security mechanism in the SAML handshake is the cryptographic validation of XML Signatures (XML-DSig) - which establishes the trust chain between IdPs and SPs. XML-DSig validation should always be done prior to executing business logic; however, the separation between signature verification and operating on the rest of a SAML payload opens up SAML authentication to vulnerabilities exposed by what are called XML Signature Wrapping (XSW) attacks. These attacks have numerous permutations which can result in outcomes such as (but not limited to):

Denial-of-service by inserting arbitrary elements that that lead to buffer overflows.
Escalating permissions by injecting assertions that allow an adversary to impersonate and be authenticated as another user, like an account admin.

The exploit here consists of modifying the payload without invalidating any signatures - think SQL Injection or Cross Site Scripting, but for for XML.

Original response (pre-XSW):

<Response ID="foo">
  <Signature>
    <SignedInfo>
      <Reference URI="#foo">...</Reference>
    </SignedInfo>
  </Signature>
  <Assertion ID="bar">
    <Signature>
      <SignedInfo>
        <Reference URI="#bar">...</Reference>
      </SignedInfo>
    </Signature>
  </Assertion>
</Response>

Modified response (post-XSW):

<Response ID="xsw">
  <Signature>
    <SignedInfo>
      <Reference URI="#foo">...</Reference>
    </SignedInfo>
    <Response ID="foo">
      <Assertion ID="bar">
        <Signature>
          <SignedInfo>
            <Reference URI="#bar">...</Reference>
          </SignedInfo>
        </Signature>
      </Assertion>
    </Response>
  </Signature>
  <Assertion ID="snek"></Assertion>
</Response>

The broadest countermeasure to XSW attacks is validating the schema of the SAML XML document. Payloads for SAML responses of any given IdP should have a deterministic standard schema that can be used as a reference in a schema compliance validation module, which should be executed prior to XML-DSig verification. Here are example schemas used by OneLogin’s python3-saml package to perform XML schema validation. Schemas should be vetted local copies as opposed to being fetched from 3rd party remote locations at runtime or on server start.

All of that being said, schema validation isn’t foolproof; there is room for error in the validation module logic itself, as well as in the syntactic rigor of the reference schema. A second low-hanging countermeasure to XSW attacks that should be employed for the sake of redundancy is to always use absolute XPath expressions to select elements in processes post-schema validation. Explicit absolute XPath expressions set an unambiguous expectation for the location of elements.

Here’s an example of a valid response that’s been modified in an XSW attack (specifically a signature exclusion attack, more on that later):

<Response ID="foo">
  <Assertion ID="snek">...</Assertion>
  <Assertion ID="bar">
    <Signature>
      <SignedInfo>
        <Reference URI="#bar">...</Reference>
      </SignedInfo>
    </Signature>
  </Assertion>
</Response>

This modification also exploits the common, incorrect, but not unreasonable assumption that a well-formed SAML response will only ever have a single assertion. So while XML-DSig verification would succeed for the signature returned by doc.getElementsByTagName(“Signature”)[0], the assertion returned and processed by doc.getElementsByTagName(“Assertion”)[0] would be the injected snek assertion. This attack would have been more likely to fail if the XPath expression “/Response/Assertion[0]/Signature” was used in the assertion signature validation logic.

Check that you’re the intended recipient

This sounds obvious, but make sure to check that a SAML response is intended for your app. This is low-hanging fruit that can prevent attacks exploiting IdPs that use a shared private signing key for all integrated SPs of a given tenant, as opposed to issuing unique keys per application. The most common attack entails the unauthorized lateral movement by a malicious user across an enterprise’s IdP-integrated apps:

A second scenario would be a third party impersonating your app and gaining user access. The likelihood of this attack vector being exploited is pretty low because the malicious party would need to be in possession of the IdP’s private signing key (among other things) - but we’re mentioning it for the sake of completeness:

There are Service Providers that don’t bother to check if they’re the intended recipient, relying only on the validity of assertion signatures to prove the sender is a trusted party and that the response is valid. But as we’ve illustrated above, valid signatures aren’t enough to prevent unwanted access.

When dealing with security and authentication, stay paranoid my friend, and have some additional redundancies to catch edge cases. In this case, some easy-to-implement checks are:

The response destination is present, non-empty, and refers to an ACS URL that you are expecting.
The response and assertion issuers refer to an IdP EntityID you recognize.
You are the specified audience for any assertions.

<Response Destination="https://api.your-app.com/auth/okta/callback">
  <Issuer>http://www.okta.com/abcd123</Issuer>
  <Assertion>
    <Issuer>http://www.okta.com/abcd123</Issuer>
  </Assertion>
  <Conditions>
    <AudienceRestriction>
      <Audience>https://api.your-app.com/auth/okta/callback</Audience>
    </AudienceRestriction>
  </Conditions>
</Response>

Validate every signature

Like we mentioned earlier, cryptographic validation of signatures is the primary mechanism for determining the authenticity of SAML payloads. It’s a good idea to read through the W3C specs for XML signature processing because it anchors SAML security, but the pithy statement to remember when handling SAML responses is only process entities that are validly signed.

There’s a class of attacks that exploit poorly implemented SP security logic known as signature exclusion attacks. These attacks will insert forged unsigned elements, banking on the possibility that the SP’s security logic will skip XML-DSig validation if no signature is found. Another common slipup is implementing validation logic that checks only the first assertion’s signature and then assumes remaining assertions are signed. Here are some rules to follow to avoid the most common oversights:

→ The entire SAML response itself should be signed

→ Every assertion should be signed

Something to note is that you should not assume a response will have only one assertion, and furthermore, each assertion should be signed in its entirety.

→ Only accept encryption schemes from an explicitly defined set of algorithms

JWT validation similarly can sometimes overlook this point, and in fact, there was a related Auth0 vulnerability exposed as recently as last year. If possible, we suggest hardcoding your validation logic to only accept RS256 as the encryption scheme. Otherwise, verify Algorithm attribute values are from a recognized set of URIs.

Bad:

<ds:SignatureMethod Algorithm=""/>

<ds:SignatureMethod Algorithm="none"/>

Good:

<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>

If you’re planning on using a third party library to do SAML processing and XML-DSig validation, be sure to vet what it does under the hood - especially if it does XML parsing and processing as well. As much as possible, try to avoid libraries that depend directly or indirectly on xmlsec1 or its dependency libxml2 - many SAML and XML libraries are just language-specific bindings for xmlsec1 and libxml2, and as a result, inherit all the same security vulnerabilities.

We highly suggest doing XML-DSig validation in native code - in fact, at WorkOS we built our SAML library from scratch for greater control, and so we can respond immediately to newly discovered SAML-related vulnerabilites.

Use the canonicalized XML

XML canonicalization is the process of transforming an XML document into a semantically identical but normalized representation (more on this later). The CanonicalizationMethod specifies which canonicalization algorithm to apply - the most commonly occurring one we’ve seen is xml-exc-c14, which strips XML comments during transformation. This generally wouldn’t be a problem, except for the fact that most SAML libraries perform canonicalization prior to doing XML-DSig validation on the canonicalized assertions. Why is this a concern? Here’s what can happen if the library’s underlying XML element text extraction logic doesn’t consider inner comment nodes.

Suppose I’m a disgruntled developer who would dearly like a substantial raise from my company that uses Okta + PayrollService (this is all fictional, I’m not disgruntled). I used to work at PayrollService and so am pretty confident this exploit I’m about to attempt will work, because patching it never got prioritized in favor of feature work, and because no one external has noticed anything amiss, yet... Anyway.

I know that WorkOS IT always uses itadmin@workos.com as an administrative account for every app used within the organization (we don’t actually). So equipped with this knowledge and using my personal domain, I create a PayrollService account for a user itadmin@workos.com.disgruntled.dev and set up SSO with Okta. Self-service free trials FTW.

Here’s a simplified SAML assertion authenticating me as a PayrollService user:

<Assertion ID="id123">
  <Signature>
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
      <Reference URI="#id123">
    </SignedInfo>
    <SignatureValue>...</SignatureValue>
    <KeyInfo>...</KeyInfo>
  </Signature>
  <Subject>
    <NameID>itadmin@workos.com.disgruntled.dev</NameID>
  </Subject>
</Assertion>

Now I can modify the SAML assertion by adding a comment:

<Assertion ID="id123">
  <Signature>
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
      <Reference URI="#id123">
    </SignedInfo>
    <SignatureValue>...</SignatureValue>
    <KeyInfo>...</KeyInfo>
  </Signature>
  <Subject>
    <NameID>itadmin@workos.com<!---->.disgruntled.dev</NameID>
  </Subject>
</Assertion>

This modified assertion doesn’t invalidate the signature because canonicalization will strip comments before XML-DSig verification - it will have the same canonical representation as the unmodified assertion. Great!

So now, believing the assertion is authentic, PayrollService checks to see which user is being authenticated. Its SAML library grabs the user identifier from the NameID element, but it, incorrectly, only reads the inner text of the element’s first node, i.e. itadmin@workos.com. Then PayrollService determines that itadmin@workos.com is indeed a user, and just like that, I’m in and ready to approve raises for myself and all my friends!

Duo Labs discovered this vulnerability back in 2018, and while some of the more commonly used open source SAML libraries have since addressed it, there undoubtedly remain many internal or open source libraries that haven’t. So echoing recommendations from before, vet your SAML and XML libraries.

Ideally, comments wouldn’t be purged prior to XML-DSig validation, so that injected comments would indeed cause validation to fail - but that’s unrealistic or inadvisable to try to enforce for a couple reasons, which we’ll leave for another time. Instead, you’ll want to make sure that:

The canonicalized XML document is used in processes post-signature verification.
Or, barring the first, that full text-extraction is handled gracefully when inner comments exist.

Avoiding replay attacks

Replay attacks occur when a SAML response is captured and re-sent to the Service Provider for duplicate processing, which can have outcomes like denial-of-service for your users, or if the SP charges by API request, eating up request quotas. The most robust countermeasure against replay attacks is preventing the capture of SAML responses in the first place - which can be accomplished by using HTTPS (should be a given already) and never exposing the SAML response to the browser. Here’s what the authentication flow could look like:

However, very few IdPs actually support the Artifact Resolution Protocol, a requirement of back-channel SAML authentication. As a result, most SAML implementations rely entirely on the browser to relay SAML payloads between the SP and IdP:

Because the SAML response is exposed to the user agent, it becomes trivial to capture (by inspecting the dev console, XSS, or with malicious browser plugins) and replay a response. So another approach to mitigating replay attacks is to maintain a cache of previously seen assertion IDs, immediately rejecting responses containing any assertion with an ID that already exists in the cache. A cache item could have a TTL equal to the expiry datetime of the originating assertion, for example:

<Assertion>
  <Conditions NotBefore="2020-08-12T02:40:30.657Z" NotOnOrAfter="2020-08-12T02:50:30.657Z">
    <AudienceRestriction>
      <Audience>https://api.foo.com/auth/callback</Audience>
    </AudienceRestriction>
  </Conditions>
</Assertion>

A third much less robust but much faster to implement countermeasure (which should be implemented regardless) is logic that strictly enforces the validation window for assertions.

One last thing to note is that most SPs that implement SAML SSO use 3rd party open source SAML libraries for speed to value, yet are not protected against replay attacks because the strongest countermeasures require additional architectural changes.

Conclusion

As with most software engineering, building SAML SSO for enterprises follows the 90-90 rule. There’s a hill to climb to get to an MVP, and an entirely different hill if you’d like to sleep at night. SAML-based authentication is rife with sleeping dragons, of which this guide only introduces a very small subset - but hopefully it has been useful in helping you avoid some of them. If product requirements allow, try to avoid integrating with IdPs using SAML; a more modern, safer, and simpler alternative protocol is OpenID Connect. And if you’re thinking twice about building SAML SSO yourself in-house, then consider using a 3rd party vendor that makes it their business to provide a safe, performant, highly available, and super fast to integrate SSO API... like WorkOS!

Additional references and further reading

The Developer’s Guide to SSO

WorkOS Developer Relations — Fri, 22 Jan 2021 19:59:09 +0000

If you want more people using your product, the easiest place to start is making it easier to actually sign up. Adding SSO to your app will help you land those larger enterprise deals and decrease the signup friction that keeps causing your visitors to drop off. For modern developers though, the world of XML, SOAP, and OASIS standards can be opaque. Fear not: our guide will walk you through SSO: what it is, why it’s important, and best practices for getting it up, running and integrated with your app.

The basics: what SSO is and why you should care

The easiest way to understand SSO quickly is to think about your app’s authentication as a service. Most developers build the service themselves: you take care of creating usernames and passwords, adding them into a database, and checking credentials every time someone logs in. But in the same way that you skip building payments infrastructure and use Stripe, you can “outsource” your auth and have someone else do it; and that’s what SSO is.

If you’ve heard of SSO before, you’re probably thinking of it as a security feature, and that’s true; but where it really shines is through increasing engagement. Making it easier to sign up for and sign into your product lowers friction for users, increases retention through smoother login flows, and helps you land those elusive enterprise deals (many enterprises can’t work with vendors who don’t support SSO).

Apps with SSO enabled allow users to authenticate through someone else’s service: instead of you managing usernames and passwords, you integrate with a provider like Okta or OneLogin that does it for you. Those services – called Identity Providers, or IDPs if you want to save time – are generally more full featured and secure than what your typical growing startup would be able to build themselves.

SSO is a given among everyone from high growth startups to more traditional enterprises. Here’s the Dropbox sign in page for SSO:

Slack, Asana, Notion, Airtable, and Trello all support SSO too, and some even charge extra for it (you can find them on the SSO Wall of Shame). It’s pretty much part of the standard growth playbook.

Learning the lingo: SAML, SPs, IDPs, and assorted acronyms

Let’s get a little deeper into how SSO works. One thing worth noting: SAML isn’t the only protocol you can use to implement SSO. OAuth (1.0 and 2.0) are also popular, as well as WS-Fed and OpenID Connect. The broad concepts can carry over across protocols, too.

If you’re integrating SSO into your app, you’re a service provider (SP). Your app is the service. The provider that you’re “outsourcing” identity to – like Okta or OneLogin – is called the identity provider (IDP). Simple enough, right? Where things start to get a bit more complex is when your app needs to communicate with identity providers to actually authenticate your users. SSO works with a communication protocol called SAML (security assertion markup language) that governs these phone lines.

SAML – and by extension, how you build and work with SSO – works through assertions.

Let’s walk through a typical SAML flow, starting with a user trying to sign in through your site.

1. The SAML request from the SP

When a user navigates to your login page (to log in, of course), they’ll either enter their email or click a button that takes them to an IDP portal like Okta. Your app issues a SAML request (and a browser redirect) to the IDP: it’s basically saying “hey, this user wants to sign in, do me a favor and verify that I should let ‘em in.”

2. The SAML assertion from the IDP

At the IDP, they’ll enter their full credentials, and deal with more extensive security measures like 2FA. Once they’ve successfully authenticated with the IDP, the IDP sends your app a response containing an assertion: this user is good to go, and you can let them in.

SAML works via XML (for all those SOAP fans out there. Nobody? Ok). Here’s an example of what an a response containing an assertion might look like (thanks to OneLogin):

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6" Version="2.0" IssueInstant="2014-07-17T01:01:48Z" Destination="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685">
  <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>

  <saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="pfxa099680e-6fc0-2c7a-90fa-4202bb29faa4" Version="2.0" IssueInstant="2014-07-17T01:01:48Z">
    <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
        <ds:Reference URI="#pfxa099680e-6fc0-2c7a-90fa-4202bb29faa4">
          <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          </ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

          <ds:DigestValue>YOCfzMPwhVQibcTRRyuCb5vlT DU=</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>

      <ds:SignatureValue>VXQGwtQsc/rTuCFspZwD6k4i6fKr4ymYfCiI5Ve9JO5LYRG7VNPzIq5Mr/JW/0btpui4cmQVK//wA89nLe+g2wxDizx32CnOBsshoF3YTDOs586SJt+Ty/h/X886Xhqu8XsdMiD/spyU8rGhIQP2OL65k6HoSFxtPqKt1+KOdkE=</ds:SignatureValue>

      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJ1czETMBEGA1UECAwKQ2FsaWZvcm5pYTEVMBMGA1UECgwMT25lbG9naW4gSW5jMRcwFQYDVQQDDA5zcC5leGFtcGxlLmNvbTAeFw0xNDA3MTcxNDEyNTZaFw0xNTA3MTcxNDEyNTZaMFIxCzAJBgNVBAYTAnVzMRMwEQYDVQQIDApDYWxpZm9ybmlhMRUwEwYDVQQKDAxPbmVsb2dpbiBJbmMxFzAVBgNVBAMMDnNwLmV4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDZx+ON4IUoIWxgukTb1tOiX3bMYzYQiwWPUNMp+Fq82xoNogso2bykZG0yiJm5o8zv/sd6pGouayMgkx/2FSOdc36T0jGbCHuRSbtia0PEzNIRtmViMrt3AeoWBidRXmZsxCNLwgIV6dn2WpuE5Az0bHgpZnQxTKFek0BMKU/d8wIDAQABo1AwTjAdBgNVHQ4EFgQUGHxYqZYyX7cTxKVODVgZwSTdCnwwHwYDVR0jBBgwFoAUGHxYqZYyX7cTxKVODVgZwSTdCnwwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQ0FAAOBgQByFOl+hMFICbd3DJfnp2Rgd/dqttsZG/tyhILWvErbio/DEe98mXpowhTkC04ENprOyXi7ZbUqiicF89uAGyt1oqgTUCD1VsLahqIcmrzgumNyTwLGWo17WDAa1/usDhetWAMhgzF/Cnf5ek0nK00m0YZGyc4LzgD0CROMASTWNg==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </ds:Signature>

    <saml:Subject>
      <saml:NameID SPNameQualifier="http://sp.example.com/demo1/metadata.php" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">_ce3d2948b4cf20146dee0a0b3dd6f69b6cf86f62d7</saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml:SubjectConfirmationData NotOnOrAfter="2024-01-18T06:21:48Z" Recipient="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685"/>
      </saml:SubjectConfirmation>
    </saml:Subject>

    <saml:Conditions NotBefore="2014-07-17T01:01:18Z" NotOnOrAfter="2024-01-18T06:21:48Z">
      <saml:AudienceRestriction>
        <saml:Audience>http://sp.example.com/demo1/metadata.php</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>

    <saml:AuthnStatement AuthnInstant="2014-07-17T01:01:48Z" SessionNotOnOrAfter="2024-07-17T09:01:48Z" SessionIndex="_be9967abd904ddcae3c0eb4189adbe3f71e327cf93">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>

    <saml:AttributeStatement>
      <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">test</saml:AttributeValue>
      </saml:Attribute>

      <saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">test@example.com</saml:AttributeValue>
      </saml:Attribute>

      <saml:Attribute Name="eduPersonAffiliation" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">users</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">examplerole1</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

The flow we just outlined is called SP-initiated, because it started at your app, and you’re the service provider. There’s another way this can go down though: users can start at their IDP (like the Okta app directory), click on which app they want to sign into, and then authenticate and redirect. That’s called IDP-initiated.

Getting practical: how to actually add SSO to your app

Like pretty much anything in software, there are two ways to add SSO to your app: you can build it yourself or pay someone else to do it for you.

1. Building SSO from scratch

Building SSO yourself is all about handling and working with the protocol you choose: assuming you’re targeting larger companies, we’re talking about SAML here. This isn’t a technical tutorial, but here are a few high level components you’ll need to write:

A SAML controller for handling requests and providing responses to your integrated IDPs
A SAML service to verify x509 certs, entity IDs, and IDP URLs, alongside parsing SAML assertions and creating and validating SAML responses. You’ll particularly enjoy the XML parsing and IDP-specific request formats
A strategy to correctly authenticate users in your app based on the attributes that IDPs send back (you’ll need to normalize these if you’re supporting multiple customers)

If any of this sounds weirdly unfamiliar to you, that’s because it probably is: there’s a lot of upfront research required to understand the right way to do it. It’s not as simple as adding a new frontend library and skimming through the docs.

Part of the challenge of building SSO from scratch is customization: you’ll need to build SAML flows for each IDP independently. SAML is a standard, and like any good standard it’s often fractured and can sometimes be a pain to work with. As usual, XKCD gets it.

Over the past few years, the web dev ecosystem has developed a few packages that take care of some of the repeatable work. Middleware like passport.js can help you avoid building everything from scratch; or if your backend is in Python, OneLogin offers a python-saml package.

2. Use an SSO provider

If you don’t want to build SSO yourself (I mean, why would you?), there are a bunch of great third party services that offer SDKs and packages to make integration as easy as a few lines of code.

-> WorkOS (we’re biased)

WorkOS lets you add SSO to your app with just a few lines of code, and it’s completely free. Integrate once and you can support SAML with IDPs like Okta, GSuite, OneLogin, and more. Here’s what that same SAML flow above might look like with something like WorkOS:

WorkOS ships with something pretty cool – Admin Portal – that allows your end users to configure their own SSO connections to their IDP of choice.

Doing this manually is rough: you need to coordinate with enterprise IT admins, exchange URLs and certificates, and build custom infrastructure like field mappers for SAML profiles. It’s not just frustrating; it drags out the integration cycle and takes up sales, support, and success time too.

-> Auth0

Auth0 is identity as a service: they offer SSO (among other products) that easily integrates into your app and supports all of the IDPs you’d ever need. Auth0 for social connections is free up to 7K users, and plans start at $23/mo for 1K users. If you want enterprise connections (think: SAML), you’ll need to move into the Developer Pro pricing tier, which starts at $28/mo for 100 users.

-> AWS Cognito

Cognito is AWS’s identity-as-a-service product, and supports SSO with SAML, OAuth 2.0, and OpenIDConnect. Cognito supports IDPs like GSuite and Facebook, and pricing is...well, it’s AWS, so you’re on your own.

-> GCP Identity Platform

GCP’s identity-as-a-service goes by “Identity Platform” (catchy), and supports the standard feature set. It also comes with some interesting built in Google features like Machine Learning based security measures (identifying compromised accounts). Pricing starts at $0.015 per SAML MAU when you’re over 50 MAUs.

Best practices from some engineers who have done it before

Here are a few tips that might make your SSO integration process just a bit easier, whether you’re using a third party provider building it from scratch.

1. Security

Disallow username and password logins, password resets, and email address changes

If an organization is using SSO with your product, give admins the ability to disable username / password based auth for their users. It creates a more seamless SSO experience by avoiding false login starts and keeps things secure.

Enforce session timeouts

Expire idle user sessions to make sure users aren't signed in indefinitely — it's good practice to grab the SAML response's session timeout value and use that, but there are cases where having a "time to live" setting for each account is useful too.

Force sign-in for active browser sessions

If your app gets a new sign-in request, replace any currently active browser sessions with the newly authenticated session. This is particularly important for apps that lean toward multi tab use, like IDEs or CRMs.

2. Routing

Ask users for info to determine the right IDP

If you plan on supporting multiple IDPs in your SSO implementation, ask users for their email address, account subdomain, or unique account URL to determine the correct identity provider for their login.

Make sure to deep link

If you’re asking users to authenticate from an existing product page or they’re expecting to land somewhere in particular in your product, you’ll want to implement deep linking in your SAML flows. You can use SAML’s RelayState parameter to get this working.

3. UX

Disable email verification for SSO users

If your app sends verification emails on username / password signups, disable that for SSO authentication: it’s not necessary.

Use Just-In-Time (JIT) User Provisioning for first time sign-ins

JIT user provisioning automates the account creation process for users signing into your app for the first time via SAML. If they exist in their organization’s IDP, you’ll just create their account automatically instead of asking them to sign up from scratch. This lowers friction for new users significantly and helps make your app more attractive to larger orgs.

Prompt users for IDP logouts

When users log out of your app, prompt them to see if they’d like to log out of their IDP as well. The two intents often overlap, and you can save your users some time.

What to do next

If you’re convinced that it’s time to add SSO into your app (you should be, hopefully), you’ll want to start by deciding how you’re going to do it. Building it yourself can give you better customization options, but using a third party service like WorkOS will save your engineering team a lot of time and effort. Here are a few resources that might help you steer in the right direction:

For more details on SAML: Duo’s The Beer Drinker’s Guide to SAML
For more details on Passport.js: freeCodeCamp’s guide to handling auth with passport.js
For more details on JIT: JumpCloud’s What is Just-In-Time User Provisioning?