Problem
When setting up SSO in a Terraform organization, turning on team membership management may not have the desired results. It is possible that turning on this setting results in users losing access to their teams, including administrator rights. Or, users being put into teams they do not belong in.
Prerequisites
This KB applies to Terraform Cloud and Terraform Enterprise organizations with single sign on and SSO team management enabled.
Cause
Terraform's SSO functionality takes the exact input coming from a user's SAML assertion and translates it into their team membership rights, among other things. When the team membership isn't reflective of what is expected, it is typically the result of the SAML assertion not being formatted correctly.
Terraform expects the exact names of the teams to be passed through the assertion, it is case sensitive and will read all input from the assertion including extra whitespace. Passing full team DNs, team names that are case mismatched, or any typos of the sort will result in users not getting their teams in Terraform.
To determine what is incorrect on a SAML assertion, the first step is to capture and decode the assertion. The assertion should look like this.
MemberOf is the specific section to look at. What to look for in this section is that the attributeName= is the correct name and that the values inside of the >brackets< are an exact match to the team names in Terraform:
<saml:AttributeName="MemberOf"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"><saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">devs</saml:AttributeValue><saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">reviewers</saml:AttributeValue></saml:Attribute>
This sample assertion will put the user into the teams devs and reviewers.
Problems with the assertion may look like this (errors in bold)
Extra white space:
<saml:AttributeName="MemberOf"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"><saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string"> devs</saml:AttributeValue><saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">reviewers </saml:AttributeValue></saml:Attribute>
Full DN:
<saml:AttributeName="MemberOf"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"><saml:AttributeValuexmlns: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, case or spelling:
<saml:AttributeName="memberof"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"><saml:AttributeValuexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xs:string">admins</saml:AttributeValue></saml:Attribute>
Solution
To resolve SAML assertion errors, please work with an IDP administrator, as the configuration of the SAML assertion sits on the IDP side of this integration. This document, as well as our sample SAML assertion and response can be provided to the administrator along with a captured SAML assertion to explain what needs to be adjusted.
As an example, in Okta, the data that needs to be repaired is located in the directory under groups. From groups, a group name can be selected and edited. The location of this data in the IDP varies depending on the provider.