Problem
In an organization with SAML or SSO enabled, HCP Terraform or Terraform Enterprise users are automatically removed from their assigned teams after logging in.
Cause
This behavior occurs when SAML is configured to manage team memberships. Once enabled, HCP Terraform and Terraform Enterprise rely on the SAML assertion from the identity provider (IdP) as the single source of truth for team assignments.
When a user logs in, their team membership is synchronized with the information in the SAML assertion:
- Users are automatically added to teams included in their assertion.
- Users are automatically removed from any teams that are not included in their assertion.
This process overrides any team memberships that were set manually in the UI. HCP Terraform will not automatically create new teams if the team names in the assertion do not match existing teams; it will ignore them.
In Terraform Enterprise, you can confirm this behavior by checking the ptfe_atlas audit logs for remove_member actions where the actor is SAML.
{
"resource": "team",
"action": "remove_member",
"resource_id": "team-otyig8fsWXNUSCZP",
"organization": "TEST-TFE",
"actor": "SAML",
"timestamp": "2021-01-21T15:19:34Z",
"user": "admin",
"actor_ip": null
}To access this log, connect to the Terraform Enterprise instance via SSH and run the following command.
# sudo docker logs ptfe_atlas
To test this behavior in either product, you can manually add a user to a team that you know is not in their IdP configuration. When the user next logs in, they should be automatically removed from that team.
Solutions
The appropriate solution depends on whether you want to manage teams within the Terraform product or through your identity provider.
Solution 1: Manage Teams in the Terraform UI
This approach disables SAML-based team management, allowing you to control team memberships manually within the product UI.
For Terraform Enterprise
- As a site administrator, navigate to the SAML settings page.
- Uncheck the Use SAML to manage team memberships checkbox.
- Save the settings. You can now manage teams on the organization’s Teams page without SAML interference.
For HCP Terraform
- As an organization owner, navigate to the organization’s SSO settings.
- Temporarily disable the SSO integration.
- Click Edit settings.
- Turn off the Enable team management to customize your team attribute setting.
- Save the settings and re-enable the SSO integration.
Solution 2: Manage Teams via the Identity Provider
This approach uses the IdP as the source of truth for team memberships. To use this method, you must configure your IdP to send the correct team membership information in the SAML assertion for each user. This ensures that users are always assigned to the correct teams upon login.
For detailed instructions, refer to the documentation on Configuring Team Membership Mapping.