Problem
After adding a SAML-authenticated user to a team in Terraform Enterprise (TFE) or HCP Terraform, the user does not immediately receive the expected permissions. The user may still be unable to access workspaces or perform actions associated with the team, receiving authorization or access denied errors. While the UI may reflect the new team membership, the permissions are not applied until the user's session is refreshed.
This issue occurs in environments using SAML Single Sign-On (SSO) with IdP-managed identities.
Cause
When SAML is enabled, Terraform Enterprise and HCP Terraform evaluate team membership and permissions at login time. If a user is already logged in when an administrator adds them to a team, their existing session token does not automatically update to reflect the new permissions. The application does not proactively reissue SAML assertions for active user sessions.
Solutions
The user must refresh their SAML session for the new team membership to take effect.
Solution 1: Log Out and Log Back In (Recommended)
The most direct way to resolve the issue is for the user to perform a full logout and log back in.
- Have the affected user log out of Terraform Enterprise or HCP Terraform.
- The user must log back in using SAML authentication.
- Confirm the user now has the expected access and permissions.
Solution 2: Wait for Session Expiration
If a user cannot log out immediately, their access will update automatically once their current SAML session expires. After expiration, the user will be prompted to re-authenticate, at which point the new team permissions will be applied. The session duration is controlled by your organization's Identity Provider (IdP) configuration.
Outcome
After the user re-authenticates, their permissions will align with their new team's access level, and they will be able to access workspaces and perform actions as expected.
Additional Information
- This behavior is an expected aspect of SAML integration and is not a bug.
- Any changes to teams, roles, or permissions for SAML-authenticated users require a session refresh to take effect.
- This behavior does not affect users authenticated via local accounts or other non-SSO methods.
- To manage user expectations, inform them that they must re-login after you grant them new permissions.
- For more details on configuring SAML, refer to the official documentation for HCP Terraform or Terraform Enterprise.