Terraform SSO team membership troubleshooting

Problem

When you configure Single Sign-On (SSO) in an HCP Terraform or Terraform Enterprise organization, enabling SSO team management may not produce the expected results. Users may lose access to their teams, including administrator rights, or they may be assigned to incorrect teams.

Prerequisites

• An HCP Terraform or Terraform Enterprise organization with SSO enabled.
• SSO team management is enabled for the organization.

Cause

HCP Terraform and Terraform Enterprise use the exact input from a user's SAML assertion to determine team membership. When team assignments are incorrect, the cause is typically a misformatted SAML assertion from the Identity Provider (IdP).

The application expects the exact team names to be passed in the assertion. The matching process is case-sensitive and includes any extra whitespace. Passing full team Distinguished Names (DNs), mismatched case, or typos will prevent users from being correctly assigned to their teams.

To identify formatting issues, you must first capture and decode the SAML assertion. Focus on the MemberOf attribute, ensuring the attributeName is correct and the values match the team names in your organization exactly.

Example: Correct SAML Assertion

A correctly formatted assertion for a user in the devs and reviewers teams appears as follows.

<saml:Attribute Name="MemberOf" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">devs</saml:AttributeValue>
  <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">reviewers</saml:AttributeValue>
</saml:Attribute>

Common Assertion Formatting Errors

Extra Whitespace

Leading or trailing whitespace within the attribute values will cause a mismatch.

<saml:Attribute Name="MemberOf" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> devs </saml:AttributeValue>
  <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> reviewers </saml:AttributeValue>
</saml:Attribute>

Full Distinguished Name (DN)

The assertion must contain the simple team name, not the full DN.

<saml:Attribute Name="MemberOf" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">cn=Finance,ou=Users,dc=example,dc=local</saml:AttributeValue>
</saml:Attribute>

Incorrect Team Mapping Attribute

Incorrect spelling or case in the Name field for the MemberOf attribute will cause the assertion to fail.

<saml:Attribute Name="memberof" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
  <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">admins</saml:AttributeValue>
</saml:Attribute>

Solution

To resolve SAML assertion errors, you must correct the configuration within your Identity Provider (IdP), as the IdP generates and controls the assertion content.

Work with your IdP administrator to make the necessary adjustments. You can provide them with this article, a captured SAML assertion from a failed login attempt, and the official documentation to explain what needs to be changed.

For example, in Okta, you can typically find this data in the directory under Groups. From there, you can select and edit a group name to ensure it matches the team name in HCP Terraform or Terraform Enterprise. The location of this data varies by IdP.

Additional Information

• For more details on IdP configuration, refer to the sample SAML assertion and response documentation.