Unpacking SAML with AppMaps and VSCode
Tags: vscode, security, architecture, ruby
Published: 2021-02-02 22:22:44

I recently came across a thorough blog post from [Osso on the ins and outs of the SAML authentication protocol](https://ossoapp.com/blog/saml-sso-rails/). In a former life, I was co-founder and CTO of cloud security company [Conjur](https://www.conjur.org/), 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](https://github.com/land-of-apps/saml-rails/tree/single-tenant) 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](https://github.com/enterprise-oss/saml-rails/compare/single-tenant...land-of-apps:single-tenant) 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*

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

And second, I added [this flag](https://github.com/enterprise-oss/saml-rails/compare/single-tenant...land-of-apps:single-tenant#diff-c1fd91cb1911a0512578b99f657554526f3e1421decdb9e908712beab57e10f9R15) 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:

```sh-session
$ APPMAP_RECORD=true bundle exec rails s
```

The login flow looks like this:

![saml-rails login](https://dev-to-uploads.s3.amazonaws.com/i/mhqyvo1pb17hcua80g6i.gif)

# 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](https://marketplace.visualstudio.com/items?itemName=appland.appmap). It looks like this (click the screenshot for a 41 second video):

[![saml-rails appmap](https://dev-to-uploads.s3.amazonaws.com/i/vd9pp6997tl1z660bb4c.png)](https://www.loom.com/share/9a0105e6bb0848b6a800f272b25d4fc9)

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](https://app.land/land-of-apps/saml-rails).

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

[![check out saml-rails](https://dev-to-uploads.s3.amazonaws.com/i/vd9pp6997tl1z660bb4c.png)](https://app.land/land-of-apps/saml-rails)

# 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?)](https://app.land/scenarios/96fc2cce-544b-4b4e-8e79-b3d77bfd525e#filterShow=sql_select%2Csql_insert%2Csql_update%2Ctrivial_functions%2Cstatic_asset_requests%2Cstack_depth_less%2Cexclude_function&filterShowParams=%7B%22stack_depth_less%22%3A%227%22%2C%22exclude_function%22%3A%22%23encrypt%2C%23decrypt%2C%23generate%2C%23digest%22%7D&event=295)

* [Sending the redirection URL](https://app.land/scenarios/96fc2cce-544b-4b4e-8e79-b3d77bfd525e#filterShow=sql_select%2Csql_insert%2Csql_update%2Ctrivial_functions%2Cstatic_asset_requests%2Cstack_depth_less%2Cexclude_function&filterShowParams=%7B%22stack_depth_less%22%3A%227%22%2C%22exclude_function%22%3A%22%23encrypt%2C%23decrypt%2C%23generate%2C%23digest%22%7D&event=313)

* [Validating the SAML response](https://app.land/scenarios/96fc2cce-544b-4b4e-8e79-b3d77bfd525e#filterShow=sql_select%2Csql_insert%2Csql_update%2Ctrivial_functions%2Cstatic_asset_requests%2Cstack_depth_less%2Cexclude_function&filterShowParams=%7B%22stack_depth_less%22%3A%227%22%2C%22exclude_function%22%3A%22%23encrypt%2C%23decrypt%2C%23generate%2C%23digest%22%7D&event=532)

* [Inserting a `user` record into the database](https://app.land/scenarios/96fc2cce-544b-4b4e-8e79-b3d77bfd525e#filterShow=sql_select%2Csql_insert%2Csql_update%2Ctrivial_functions%2Cstatic_asset_requests%2Cstack_depth_less%2Cexclude_function&filterShowParams=%7B%22stack_depth_less%22%3A%227%22%2C%22exclude_function%22%3A%22%23encrypt%2C%23decrypt%2C%23generate%2C%23digest%22%7D&event=559)

* [Storing the SAML token in the session](https://app.land/scenarios/96fc2cce-544b-4b4e-8e79-b3d77bfd525e#filterShow=sql_select%2Csql_insert%2Csql_update%2Ctrivial_functions%2Cstatic_asset_requests%2Cstack_depth_less%2Cexclude_function&filterShowParams=%7B%22stack_depth_less%22%3A%227%22%2C%22exclude_function%22%3A%22%23encrypt%2C%23decrypt%2C%23generate%2C%23digest%22%7D&event=609)

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](https://discord.com/invite/N9VUap6).