Unpacking SAML with AppMaps and VSCode

I recently came across a thorough blog post from Osso on the ins and outs of the SAML authentication protocol. In a former life, I was co-founder and CTO of cloud security company Conjur, and from that experience I know two things to be true about security protocols:

1) They are important
2) They are (usually) hard to understand

So, given the above, anything that I can do to help people understand a security protocol seems like time well spent.

Since I, and the team at AppLand, spend all day working on better ways to visualize and understand code, I thought I would see how useful our tooling can be to understanding SAML. As a result, here's a fairly short post that describes how I went about AppMapping SAML, and I will also provide a link that you can use to browse the interactive diagrams of saml-rails yourself.

Setting up

The first step was to clone and branch the saml-rails repo which was originally created by Osso.

Adding the appmap gem and configuration is covered extensively elsewhere, so I won't dive into the details of that. Use the GitHub compare view and you'll see all my changes.

I will quickly point out a couple things of interest. First, I added some gems to the appmap.yml

- gem: ruby-saml
  shallow: false
- gem: devise
- gem: actionpack

And second, I added this flag which enables me to record the server operation from beginning to end.

Recording the SAML flow

With the above in place, I just needed to run the server and step through the flow. The server command is:

$ APPMAP_RECORD=true bundle exec rails s

The login flow looks like this:

Opening the AppMap in VSCode

The recording saves a file called appmap.json. I rename it saml-rails.appmap.json, and then I can open it in the AppMap extension for VSCode. It looks like this (click the screenshot for a 41 second video):

If you want to setup this environment for yourself, you can clone my fork of the saml-rails repo and reproduce these steps.

Online browseable AppMap

If you just want to checkout the AppMaps yourself and dig into how SAML works, I've uploaded the data to https://app.land/land-of-apps/saml-rails.

This is a publicly accessible page that you can use to browse through all the data.

Points of interest

I'm not a SAML expert, but here are a few links to the app diagrams that I found interesting.

• Building the SAML auth request (which apparently is a base64 of an XML document; who knew?)

• Sending the redirection URL

• Validating the SAML response

• Inserting a user record into the database

• Storing the SAML token in the session

Hopefully, if you have questions about how SAML works, you'll find this post useful. If you have any questions about how to setup the AppMap configuration or your VSCode environment, feel free to ask here in the comments, or visit us in Discord.