Capturing a SAML Assertion

Introduction

This document outlines the methods that can be used for each of the major browsers to capture the response (assertion) that an identity provider (IdP) sends when attempting to log in to Terraform Cloud or Terraform Enterprise using SAML. The values contained within SAML assertions (attributes) are used by Terraform Cloud or Terraform Enterprise to map a login attempt to a particular user and assign attributes such as team, organization, and site admin membership.

Use Case

When troubleshooting SAML sign on for Terraform Cloud and Terraform Enterprise, it is often necessary to capture a SAML assertion in order to determine what attributes the IdP is providing. This data is crucial in helping to troubleshoot common SAML login problems.

Capturing an Assertion

Depending on the browser, there are different methods for capturing a SAML assertion. Below are the necessary steps to capture an assertion on three of the major internet browsers. Decoding the response retrieved will be covered later in this document.

Chrome (as of 89.0.4389.90)

1. Navigate to the Terraform Cloud or Terraform Enterprise login page.
2. Click “Sign in with SSO”.
3. (Terraform Cloud) Enter the name of an organization that has SAML enabled.
4. Click the stacked dots menu to the right side of the search bar and choose More Tools > Developer Tools.
5. Click on the Network tab and enable Preserve Log.
6. Complete the SAML sign in flow.
7. Locate and click on the document named “acs” (when using Terraform Cloud) or “auth” (when using Terraform Enterprise).
8. Scroll to the bottom and review the Form Data. The base64 encoded SAML assertion will be listed here as the SAMLResponse.
9. Save the response string so that it may be decoded in the later steps of this article.

Firefox (as of 87.0)

1. Navigate to the Terraform Cloud or Terraform Enterprise login page.
2. Click “Sign in with SSO”.
3. (Terraform Cloud) Enter the name of an organization that has SAML enabled.
4. Open the “Network” Web Developer pane by navigating clicking Tools > Web Developer > Web Developer Tools and selecting “Network”.
5. Click the gear in the upper right corner of the Web Developer tools pane and enable Persist Logs.
6. Click “Next” on the sign in page.
7. Complete the SAML sign in flow.
8. In the Web Develop pane, look for a POST to [app.terraform.io](http://app.terraform.io) (Terraform Cloud) for a file named acs. On Terraform Enterprise, this POST will be to the Terraform Enterprise hostname and the file will be called auth. Click on this request to open it for viewing.
9. In the “Request” tab of the request inspector, locate the “Form data” section, which contains a SAMLResponse parameter. This value is the base64 encoded SAML assertion.
10. Save the response string so that it may be decoded in the later steps of this article.

Safari (as of 14.0.3)

In order to capture an assertion in Safari, the Develop menu must first be enabled. The following steps will outline enabling this menu.

1. Open Safari preferences.
2. Navigate to the “Advanced” tab.
3. Enable the “Show Develop menu in menu bar” option.

Once the Develop menu has been enabled, a SAML assertion may be captured using the following steps.

1. Navigate to the Terraform Cloud or Terraform Enterprise login page.
2. (Terraform Cloud) Click “Sign in with SSO”.
3. (Terraform Cloud) Enter the name of an organization that has SAML enabled.
4. From within Safari’s Develop menu, click to open web inspector, then select the “Network” tab.
5. In the upper right corner of the web inspector, click the check box to enable the “Preserve Log” option.
6. Log in to Terraform Cloud or Terraform Enterprise using SAML.
7. Within the web inspector, locate and click on the document titled with the name of the Terraform Cloud organization that you are logging into. In Terraform Enterprise, the title of the document is “app”.
8. Click on the “Headers” section to the right of the file explorer and scroll to the bottom of the field to locate the “Request Data” section and click on the arrow to the right of the “Request Data” field within it.
9. Copy all of the text between SAMLResponse= and &RelayState=; this is the base64 and URI encoded SAML assertion.
10. Save the response string so that it may be decoded in the later steps of this article.

Decoding an Assertion

Once the base64 encoded assertion has been retrieved from the browser, it needs to be decoded to it’s human-readable XML format.

macOS / Linux

To decode an assertion on a machine running macOS or Linux, save the base64 encoded assertion to a file, then open a terminal and run the following command.

$ echo $ENCODED_RESPONSE | base64 --decode

For the assertion retrieved from Safari, an extra step has to be taken as it is URI encoded as well as base64 encoded. To cope with this, edit the string in your text editor of choice to replace all occurrances of %2B with + before decoding as described above. Alternatively, an example using sed is provided below.

$ echo $ENCODED_RESPONSE | sed 's/%2B/\+/g' | base64 --decode

Windows

To decode an assertion on a Windows machine, save the base64 encoded assertion to a file, then open the command prompt and run the following command.

certutil -decode C:\path\to\encoded_saml_response.txt C:\path\to\decoded_saml_response.txt

Additional Information

There are third party tools, such as the SAML Tracer add-on for Firefox or Chrome that make capturing and decoding SAML assertions easier. These tools may be useful if capturing SAML assertions is a task performed on a regular basis, or if any issues are encountered with the steps in this article.