Resolving SAML Group Sync Issues Between Azure AD and Terraform Enterprise (TFE)

Problem

Users in Azure Active Directory (AD) groups are not correctly mapped to corresponding teams in Terraform Enterprise (TFE) via SAML, even when the SAML configuration appears valid. This can result in users being unable to access the TFE organization or its resources as expected.

Prerequisites

• You have configured SAML authentication in Terraform Enterprise.
• You have set up Azure AD as the Identity Provider (IdP).

Cause

This issue can occur due to one or more of the following reasons:

• Case Sensitivity: Terraform Enterprise team names do not have an exact, case-sensitive match with the SAML attribute values (e.g., sesre vs. SESRE).
• Attribute Mismatch: The SAML assertion sends either GUIDs (Group IDs) or sAMAccountName values that do not align with TFE’s team names or configured SSO Team IDs.
• Team Configuration: Terraform Enterprise teams lack an explicit mapping to Azure AD groups via their GUIDs in the SSO Team ID field.

Solutions

Here are two methods to resolve this issue. Using the Group ID is the recommended approach as it is more resilient to name changes.

Solution 1: Use Group IDs for Team Mapping (Recommended)

This method creates an explicit link between an Azure AD group and a Terraform Enterprise team using the group's unique GUID.

Procedure

1. Azure AD Configuration: In your SAML application's Group Claims settings, set the Source attribute to Group ID. This ensures the Azure AD group’s GUID is included in the SAML assertion.
2. Terraform Enterprise Configuration: Navigate to Organization Settings > Teams > [Your Team Name]. In the SSO Team ID field, enter the exact GUID of the corresponding Azure AD group and save the changes.

This approach works because Terraform Enterprise matches the GUID from the SAML assertion directly to the value in the SSO Team ID field, bypassing any potential mismatches in team names.

Solution 2: Use sAMAccountName for Team Mapping

This method relies on ensuring the team name in Terraform Enterprise is an exact, case-sensitive match for the sAMAccountName sent by Azure AD.

Procedure

1. Azure AD Configuration: In your SAML application's Group Claims settings, set the Source attribute to sAMAccountName. This ensures the group’s sAMAccountName (e.g., sesre) is included in the SAML assertion.
2. Terraform Enterprise Configuration: Rename the Terraform Enterprise team to exactly match the sAMAccountName value from Azure AD. This match must be case-sensitive. For example, if the SAML assertion sends sesre, the TFE team must be named sesre, not SESRE.

This approach works because Terraform Enterprise automatically attempts to map users to teams by finding an exact-case match between the SAML attribute value and existing team names.

Additional Information

• SAML Team Membership in Terraform Enterprise
• Single Sign-On: Team Names and SSO Team IDs