Capturing a SAML Assertion

Steps

Introduction

This document explains how to capture the SAML response (assertion) that an identity provider (IdP) sends when a user logs in to HCP Terraform or Terraform Enterprise. Attributes in the assertion are used to map the login to a user and assign permissions such as team, organization, and site‑admin membership.

Use Case

When troubleshooting SAML sign‑on problems for HCP Terraform or Terraform Enterprise, you must capture the SAML assertion to see which attributes the IdP provides. This information is essential for diagnosing common login failures.

Procedure

The method for capturing a SAML assertion varies by browser. The steps below cover three major browsers; decoding the response is described later.

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. Open the Chrome menu (three dots) to the right of the address bar and select More Tools > Developer Tools.
5. Select the Network tab and enable the Preserve Log checkbox.
6. Complete the SAML sign‑in flow.
7. In the Network tab, locate the request 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 appears as the SAMLResponse.
9. Save the response string for decoding 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 Web Developer Tools via Tools > Web Developer > Web Developer Tools and select the Network tab.
5. Click the gear icon in the upper‑right of the 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, locate the POST request to the Enterprise hostname for a file named auth.
8. Click the request to view its details.
9. In the Request tab, locate the Form data section containing the SAMLResponse parameter. This value is the base64‑encoded SAML assertion.
10. Save the response string for decoding in the next section.

Capturing an Assertion in Apple Safari (as of 14.0.3)

First, enable the Develop menu.

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

After enabling the Develop menu, capture the SAML assertion as described below.

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 the Safari Develop menu, open the Web Inspector and select the Network tab.
5. In the upper‑right corner of the inspector, enable the Preserve Log option.
6. Complete the SAML sign‑in flow.
7. In the inspector, locate and click the document titled with your HCP Terraform organization name. For Terraform Enterprise, the document title is app.
8. Select the Headers tab and scroll to the bottom to find the Request Data section.
9. Copy all text between SAMLResponse= and &RelayState=. This is the base64‑ and URI‑encoded SAML assertion.
10. Save the response string for decoding in the next section.

Decoding the Assertion

After retrieving the base64‑encoded assertion from the browser, decode it to human‑readable XML.

macOS and Linux

Save the base64 string to a file, open a terminal, and run:

$ echo $ENCODED_RESPONSE | base64 --decode

Safari assertions are also URI‑encoded. Replace all %2B with + before decoding.

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

Windows

Save the base64 string to a file, open Command Prompt, and run:

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. Use these tools 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