Capturing a SAML Assertion

Steps

Introduction

This document outlines the methods to capture the SAML response (assertion) that an identity provider (IdP) sends when a user attempts to log in to HCP Terraform or Terraform Enterprise. The values within SAML assertions, known as attributes, are used by HCP Terraform and Terraform Enterprise to map a login attempt to a user and assign permissions such as team, organization, and site admin membership.

Use Case

When troubleshooting SAML sign-on issues for HCP Terraform and Terraform Enterprise, it is often necessary to capture a SAML assertion to determine which attributes the IdP is providing. This data is crucial for resolving common SAML login problems.

Procedure

Depending on the browser, there are different methods for capturing a SAML assertion. The steps below cover three major internet browsers. Decoding the response is covered in a later section.

Capturing an Assertion in Google Chrome (as of 89.0.4389.90)

1. Navigate to the HCP Terraform or Terraform Enterprise login page.
2. Click “Sign in with SSO”.
3. For HCP Terraform, enter the name of an organization that has SAML enabled.
4. Click the stacked dots menu to the right of the address bar and choose More Tools > Developer Tools.
5. Click the Network tab and enable the Preserve Log checkbox.
6. Complete the SAML sign-in flow.
7. In the Network tab, locate and click on the document named acs (for HCP Terraform) or auth (for Terraform Enterprise).
8. Scroll to the bottom of the details pane and review the Form Data section. The base64 encoded SAML assertion is listed as the SAMLResponse.
9. Save the response string to decode it in the next section.

Capturing an Assertion in Mozilla Firefox (as of 87.0)

1. Navigate to the HCP Terraform or Terraform Enterprise login page.
2. Click “Sign in with SSO”.
3. For HCP Terraform, enter the name of an organization that has SAML enabled.
4. Open the Web Developer Tools by navigating to Tools > Web Developer > Web Developer Tools and selecting the Network tab.
5. Click the gear icon in the upper-right corner of the Web Developer tools pane and enable Persist Logs.
6. Complete the SAML sign-in flow.
7. In the Web Developer pane, find the POST request to app.terraform.io for a file named acs (for HCP Terraform). For Terraform Enterprise, this POST request will be to the Terraform Enterprise hostname for a file named auth.
8. Click on this request to view its details.
9. In the Request tab of the inspector, locate the Form data section, which contains the SAMLResponse parameter. This value is the base64 encoded SAML assertion.
10. Save the response string to decode it in the next section.

Capturing an Assertion in Apple Safari (as of 14.0.3)

First, you must enable the Develop menu.

1. Open Safari preferences (Safari > Preferences).
2. Navigate to the Advanced tab.
3. Enable the Show Develop menu in menu bar option.

Once the Develop menu is enabled, capture the SAML assertion.

1. Navigate to the HCP Terraform or Terraform Enterprise login page.
2. Click “Sign in with SSO”.
3. For HCP Terraform, enter the name of an organization that has SAML enabled.
4. From Safari’s Develop menu, click to open Web Inspector, then select the Network tab.
5. In the upper-right corner of the web inspector, enable the Preserve Log option.
6. Complete the SAML sign-in flow.
7. In the web inspector, locate and click on the document titled with the name of your HCP Terraform organization. For Terraform Enterprise, the document title is app.
8. Click the Headers tab and scroll to the bottom to find the Request Data section.
9. Copy all of the text between SAMLResponse= and &RelayState=. This is the base64 and URI encoded SAML assertion.
10. Save the response string to decode it in the next section.

Decoding the Assertion

Once you retrieve the base64 encoded assertion from the browser, you must decode it to its human-readable XML format.

macOS and Linux

To decode an assertion, save the base64 encoded string to a file, then open a terminal and run the following command.

$ echo $ENCODED_RESPONSE | base64 --decode

Assertions retrieved from Safari require an extra step because they are also URI encoded. Before decoding, replace all occurrences of %2B with +. You can do this in a text editor or with a command.

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

Windows

To decode an assertion on Windows, save the base64 encoded string 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

Third-party tools, such as the SAML Tracer add-on for Firefox or Chrome, can simplify capturing and decoding SAML assertions. These tools may be useful if you perform this task regularly or encounter issues with the steps in this article.

• HCP Terraform: Configure and manage single sign-on
• Terraform Enterprise: Configure Terraform Enterprise as the SAML service provider