Create initial Terraform Enterprise admin user

This topic describes how to create the initial admin user for managing the Terraform Enterprise application and run workloads. Create the initial admin user after installing Terraform Enterprise. Refer to Deploy Terraform Enterprise for additional information about the deployment process.

Overview

Complete the following steps to create the initial admin user:

1. Retrieve the initial admin creation token: The initial admin creation token (IACT) is available for a limited time after starting Terraform Enterprise. You must present the token to authenticate your request to create an admin user.
2. Create initial admin user: You can create the initial admin user in two ways: using the browser or directly from the container or pod.

Requirements

Terraform Enteprise must not have any other users in the system when creating an admin user by presenting the IACT.

Retrieve initial admin creation token

You may set the initial admin creation token in TFE_IACT_TOKEN setting reference if desired. If it is set, you may proceed to Create initial admin user.

If this value is not set, a random token will be generated. By default, you have 60 minutes to retrieve the IACT upon start up. Refer to the TFE_IACT_TIME_LIMIT setting reference for additional information about changing the time limit.

You can retrieve the IACT from the Terraform Enterprise UI or from the Terraform Enterprise container or pod.

UI

Navigate to https://${TFE_HOSTNAME}/admin/retrieve-iact in your browser on a workstation to retrieve your token. The host name is one of the addresses specified in the TFE_IACT_SUBNETS setting.

Container or pod

You can retrieve your IACT token directly from the Terraform Enterprise container or pod:

$ kubectl exec -it -n <TFE_NAMESPACE> <POD_NAME> -- tfectl admin token

$ docker exec <CONTAINER_NAME> tfectl admin token

$ podman exec -it <CONTAINER_NAME> tfectl admin token

$ nomad alloc exec -namespace=<TFE_NAMESPACE> -it -task <TFE_TASK_NAME> <ALLOCATION_ID> tfectl admin token

Create initial admin user

You can create the initial admin user in the Terraform Enterprise UI or by sending a POST request to the /admin/initial-admin-user API endpoint.

UI

1. Navigate to https://${TFE_HOSTNAME}/admin/account/new?token=${IACT_TOKEN} in your browser on a workstation. The host name is one of the addresses specified in the TFE_IACT_SUBNETS setting.
2. When prompted, complete the steps to create the admin user.

Container or pod

1. Create a JSON document with the username, email address, and password for the admin user you want to create. Refer to initial-admin-user reference documentation for additional information.

   The following example payload creates a user named manage:

   {
    "username": "manage",
    "email": "it@mycompany.com",
    "password": "thisisabadpassword"
   }
   

2. Send a POST request to the /admin/initial-admin-user endpoint. You must present the IACT token. Refer to Retrieve initial admin creation token for instructions.

   The following example sends the initial admin user details in a file called payload.json:

   curl \
     --header "Content-Type: application/json" \
     --request POST \
     --data @payload.json \
     https://${TFE_HOSTNAME}/admin/initial-admin-user?token=${IACT_TOKEN}
   

The API returns a created status response:

{
  "status": "created",
  "token": "aabbccdd.v1.atlas.ddeeffgghhiijjkkllmmnnooppqqrrssttuuvvxxyyzz"
}