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

Introduction

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

Prerequisites:

1. SAML authentication is configured in TFE.

2. Azure AD is set up as the Identity Provider (IdP).

Cause:

• Case Sensitivity: TFE team names do not exactly match 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 SSO Team IDs.

• Team Configuration: TFE teams lack explicit mappings to Azure AD groups via GUIDs (SSO Team IDs).

Solutions:

Option 1: Use Group ID (Recommended)

Steps:

1. Azure AD Configuration:

   • In the Group Claims settings, set Source Attribute to Group ID.

   • Ensure the Azure AD group’s GUID is included in the SAML assertion.

2. TFE Configuration:

   • Navigate to Organization Settings > Teams > [Team Name].

   • In the SSO Team ID field, enter the exact GUID of the corresponding Azure AD group.

   • Save changes.

Why This Works:
TFE matches the GUID in the SAML assertion to the SSO Team ID, bypassing team name mismatches.

Option 2: Use sAMAccountName

Steps:

1. Azure AD Configuration:

   • In the Group Claims settings, set Source Attribute to sAMAccountName.

   • Ensure the SAML assertion includes the group’s sAMAccountName (e.g., sesre).

2. TFE Configuration:

   • Rename the TFE team to exactly match the sAMAccountName value (case-sensitive).

   • Example: If the SAML assertion sends sesre, the TFE team must be named sesre, not SESRE.

Why This Works:
TFE automatically maps users to teams based on exact-case matches between the SAML attribute and team names.

Additional Information
https://developer.hashicorp.com/terraform/enterprise/saml/team-membership
https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/single-sign-on#team-names-and-sso-team-ids