Create a local TFE Administrator through the Rails Console

Problem

After you enable Single Sign-On (SSO) in a Terraform Enterprise (TFE) instance, you may be unable to access the application if the SSO configuration is incorrect or the identity provider is unavailable. Without a local administrative recovery account, you can be locked out of the user interface.

This guide provides the procedure to create a new local administrative user directly through the TFE Rails console.

Prerequisites

• You have shell access to the TFE application server.
• You know how to access the TFE Rails console. For instructions, refer to the How To Access the Terraform Enterprise Rails Console guide.

Procedure

Follow these steps to create a local administrator and add them to an organization.

1. Access the Rails console on your TFE instance.

2. Create a new user and assign it to the u variable. This command sets the user's email, username, and password, and grants administrative privileges.

   ## Replace the example values with your desired credentials.
   irb(main):001:0> u = User.create!(email: "example@email.com", username: "example", password: "example", is_admin: true)

3. Confirm the user's account to bypass the email confirmation requirement.

   irb(main):002:0> u.confirm
   irb(main):003:0> u.save

4. (Optional) If you need the user to be an owner of a specific organization, run the following command.

   ## Replace "your-org" with the actual organization name.
   irb(main):004:0> Organization.find_by_name("your-org").add_owner!(u)

Outcome

After you complete these steps, you can use the newly created user's credentials to log into the TFE instance without using SSO. This access allows you to troubleshoot and correct the SSO configuration or perform other administrative tasks.