Problem
When SAML is enabled, if there is an issue with the way site admin privileges are configured, it is possible for all users to be locked out of the site admin portal of Terraform Enterprise. This creates two problems: they cannot perform administrative functions, and because SAML configuration is an administrative function, they are unable to easily troubleshoot or deactivate SAML to repair the issue. This document explains the situation and provides a solution to restore access.
Cause
The initial user account for a Terraform Enterprise installation is the first site admin. Site admins can grant admin permissions to other users in the “Users” section of the admin pages. See Promoting a User to Administrator for details.
When SAML is active, all SAML users who require site admin permissions must have one of two attributes in their SAML assertion: the SiteAdmin attribute (recommended, and preferred when provided) or the Site Admin team membership role.
If the IdP is not correctly configured to provide one of the two, and no non-SSO admin account has been created, no user will be able to log in to Terraform Enterprise as an admin.
Solution
If the issue has already occurred, and you’re unable to determine and correct the configuration problem by working within the IdP, the only way to restore site admin access is through the application’s Rails console. See How To Access the Terraform Enterprise Rails Console for the background, security, and process for establishing a connection to the console.
-
Before connecting to the console, have the target user log in to Terraform Enterprise.
-
Once connected, run the following commands, replacing
user@example.comwith the email address of the target user.> user = User.find_by(email: "user@example.com") > user.update(is_admin: true) -
After performing the update, refresh the user session created earlier to verify that the user is now a site admin. Without logging the user out, make the necessary SAML configuration changes from the site admin area, such as disabling SAML or updating SAML settings.
Additional Information
To avoid this issue, before enabling SAML, always create a non-SSO admin account. You must create this account while SAML is inactive; user creation outside SAML is not permitted when SAML is active.
If you continue to experience issues after following this guide, please contact HashiCorp Support for further assistance.