Terraform Enterprise - Automating Initial User Creation

After Terraform Enterprise is installed, the initial admin user must then be created to begin using the product. Normally this user is created by opening the application from the installer dashboard. However, if further automation is desired, an API is available to create this user.

Initial Admin Creation Token (IACT)

To create the initial admin user via the API, the request must be authenticated with the Initial Admin Creation Token (IACT). This token can only be used to create the admin user when there are no users configured in the system. The IACT can be retrieved in several different ways.

Shell Command or Automated Deployment Script

After installation, run the following from a shell connected to your Terraform Enterprise instance:

replicated admin --tty=0 retrieve-iact

If you want to create the initial user in an automated deployment script, run a command that lets you capture the IACT. The following example command outputs the complete IACT with the carriage return character removed. The --tty=0 flag enables the command to run successfully in automation, such as cloud-init. Without this flag set, the command will return an empty string:

initial_token=$(replicated admin --tty=0 retrieve-iact | tr -d '\r')

The command outputs the complete IACT with the carriage return character removed, which facilitates use in automation.

Via API

The option iact_subnet_list can be set to a CIDR mask that will allow clients in that address range to query the retrieval API directly. This allows installers the ability to create the installation and then immediately request the IACT token without running a command on the installation machine.

The API will be relative to the installation, for example https://tfe.mycompany.com/admin/retrieve-iact, with /admin/retrieve-iact being the path that returns the token.

When this feature is used, it is governed by another setting: iact_subnet_time_limit. This is a time limit, measured from the installation starting, that controls external access to the IACT. By default this is set to 60 minutes, meaning that during the initial 60 minutes after the installation boots, the API can be used by a client within the subnet list. After that time, access is not allowed.

If a customer wishes to disable the time limit and allow access to the IACT forever, set the limit to unlimited.

Initial Admin Creation API

With the IACT in hand, the initial admin creation API can now be used. This API is available under the path /admin/initial-admin-user of your primary hostname. For instance, if your Terraform Enterprise instance was located at tfe.mycompany.com, the initial admin creation API would be https://tfe.mycompany.com/admin/initial-admin-user.

This API requires the IACT as well as a JSON document describing the username, email address, and password of the initial admin user.

Creating the Initial Admin User API

POST /admin/initial-admin-user

Query Parameters

These are standard URL query parameters; remember to percent-encode values if your tooling doesn't automatically encode URLs.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Response Body

The POST endpoint will return a JSON object with the following properties.

Sample Payload

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

Sample Request

curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data @payload.json \
  https://tfe.company.com/admin/initial-admin-user?token=$(cat iact.txt)

Sample Response

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