Five things I learned about SAML from studying a realistic example

I recently dug into execution traces of a saml-rails example app using the AppMap extension for VSCode, looking for "points of interest" in the code. Here are five interesting things that I learned about SAML and how to integrate SAML into a realistic application.

Note: The code snippets in this post are edited a little bit for brevity. For full source, click through to the links.

1) The SAML auth request is complex

When a web site wants to login a user with SAML, it sends an HTTP request that contains a specially encoded auth parameter. The auth parameter is a base64 encoding of an XML document. It's built using code that looks like this:

  request_doc = create_authentication_xml_doc(settings)
  base64_request = encode(request)
  request_params = {"SAMLRequest" => base64_request}

The XML document contains a few required parameters, and many optional ones.

In a real-world scenario, learning more about all these parameters as you review the app requirements, SAML vendor doc, and the SAML spec is going to be important. Other resources confirm my intuition about the complexity of SAML configuration.

2. The user's HTTP login request is redirected to the SAML provider

Once the base64-ed auth request is created in the previous step, the request is redirected to the SAML provider.

The encoded data is passed to the SAML provider as the SAMLRequest parameter. An example URL looks like this:

https://idp.samlprovider.com/saml-login?SAMLRequest=fZAxb8MgEIX%2FijcmbIwdKTnFlqxmiZQuSduhS0QwjVExUA5X7

Needless to say, SSL is essential throughout the process.

3. The SAML response is verified using a certificate

The saml_callback response contains a fingerprint and digital signature. Your application (a "service provider" in SAML-speak) uses the certificate public key of the SAML identity provider to verify the login response.

4. Applications can dynamically create user records in response to SAML login

When a SAML response is received and verified, it's expected that the application ("service provider", remember?) will find-or-create a user record

5. The user id is stored in the session, as normal

Once the user record is created, the user id can be stored the in the session, like any other login flow. It's good to know that this doesn't change with SAML as compared to other, less complex forms of authentication.

On the user's next request, the user id can be retrieved from the session. The user id is used to find the user record in the database, and the request continues.

While you're here

We are conducting a survey: State of Software Architecture Quality. We are aiming for 300 responses, and once we meet our goal we will be donating $1,000 to Girls Who Code. Please contribute to our understanding of software architecture quality by filling out the survey! Of course, we will be summarizing and publishing the results once they are available.

If you don't want to fill out the survey, but you want to be notified when the results are available, you can fill out this form: https://forms.gle/u8CPS3GGD6A7WHsG7.

Resources

• A good writeup of SAML for web developers.

• enterprise-oss/saml-rails repo.

• The AppMap extension for VSCode, and installation instructions for Ruby and Java.

• My blog post about how to setup AppMap recording for the saml-rails repo, so that you can explore the execution traces using AppMaps.