Adding New user to an Existing Organization Using RAIL Console (Terraform Enterprise)

Purpose

This article explains how to create a new user and add them to an existing organization in Terraform Enterprise (TFE) using the RAILS console, so that the user can log in and access the existing organization.

This approach is typically used when:

• UI-based user creation is not possible.
• Recovering or re-creating admin users

Prerequisites

Before proceeding, ensure the following:

• Admin access to Terraform Enterprise  
• Access to the TFE RAILS console 
• Basic understanding of RAILS console commands 
• The organization already exists in TFE

Step 1: Access the RAILS Console

• Log in to the Terraform Enterprise container and access the RAILS console.
• Depending on the deployment type, this may vary. For example:

docker exec -it <container name/ID> /bin/bash
tfe-admin rails console

Step 2: Create the User

• Run the following command to create a new user:

u = User.create!(
  email: "example@email.com",
  username: "admin",
  password: "XXXXXX",
  is_admin: true
)

Notes:

• Replace email, username, and password with appropriate values. 
• Set is_admin: true only if the user requires admin privileges.

Step 3: Confirm and Save the User

• Confirm the user and save the record:

u.confirm
u.save

This ensures the user is marked as confirmed and can log in successfully.

Step 4: Find the Existing Organization

• Locate the organization by name:

org = Organization.find_by!(name: "<Org Name>")

Replace <Org Name> with the exact organization name as shown in TFE.

Step 5: Associate the User with the Organization

• Create the organization–user mapping:

OrganizationUser.create!(
  user: u,
  organization: org
)

This step ensures that the user can see and access the existing organization after logging in.

Step 6: Add User to Required Team via UI

After completing the RAILS console steps:

• Log in to the Terraform Enterprise UI as an admin. 
• Navigate to: 
  • Organization → Teams 
• Add the new user to: 
  • Owners' team (if full access is required), or 
  • Any other required team based on role and permissions. 

The user will not have meaningful access until they are assigned to at least one team.

Validation Checklist

After completing all steps, verify the following:

• The user can successfully log in to TFE.
• The user can see the existing organization. 
• User has appropriate permissions based on team membership. 
• Admin access works as expected (if applicable)

Common Issues & Notes

• Creating the user alone is not sufficient—the organization mapping is mandatory. 
• Team assignment must be done via UI, not RAILS. 
• An incorrect organization name will result in a RecordNotFound error. 
• Avoid using weak or temporary passwords in production environments.