Terraform Enterprise service accounts – HashiCorp Help Center

Problem

When listing all users in Terraform Enterprise using the /api/v2/admin/users API endpoint, the response may include more users than expected. Some of these user objects have the is-service-account attribute set to true.

Cause

These service accounts are not created directly by administrators. Terraform Enterprise automatically generates them for internal operations. Common examples include accounts associated with team API tokens or Version Control System (VCS) provider webhooks.

Solution

You can identify the purpose of these service accounts by inspecting their attributes via the API and, if necessary, querying the backend application console.

Prerequisites

A Terraform Enterprise admin API token.
SSH access to the Terraform Enterprise instance for investigating team-related accounts.
The jq command-line tool is recommended for parsing JSON output. You can find installation instructions on the official jq website.

Procedure

Step 1: List Users via the API

First, set your Terraform Enterprise hostname and admin API token as environment variables.

$ export TFE_HOSTNAME="<TFE_FQDN>"
$ export TOKEN="<API_TOKEN_ADMIN_PERMISSIONS>"

Next, use curl to query the admin users endpoint and pipe the output to jq to format the results.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://$TFE_HOSTNAME/api/v2/admin/users | jq '.data[].attributes'

Step 2: Analyze the API Output

The output will include a list of user attributes. Service accounts will be clearly marked.

{
  "username": "gh-webhooks-test-yoKVgKZvO7",
  "email": "gh-webhooks-test-yokvgkzvo7@service.local",
  "avatar-url": "https://www.gravatar.com/avatar/fa3c2f0",
  "is-admin": false,
  "is-confirmed": true,
  "is-suspended": false,
  "is-service-account": true,
  "two-factor": {
    "enabled": false,
    "verified": false
  }
}
{
  "username": "api-team_5",
  "email": "api-team_5@service.local",
  "avatar-url": "https://www.gravatar.com/avatar/a2cf5b99d",
  "is-admin": false,
  "is-confirmed": true,
  "is-suspended": false,
  "is-service-account": true,
  "two-factor": {
    "enabled": false,
    "verified": false
  }
}

Based on the username and email fields, you can infer the account's purpose:

gh-webhooks-test-yokvgkzvo7@service.local: This account is related to a VCS provider named test that connects to GitHub.
api-team_5@service.local: This account is associated with an API token generated for a team with the internal ID of 5.

Step 3: Identify the Associated Team

To find which team a service account like api-team_5 belongs to, you must access the Rails console on the Terraform Enterprise instance.

SSH into your Terraform Enterprise instance.

Execute the following command to access the Rails console within the tfe-atlas container.

# docker exec -it tfe-atlas /bin/bash -c "/usr/bin/init.sh /app/scripts/wait-for-token -- bash -i -c 'cd /app && ./bin/rails c'"

Within the Rails console, run the following Ruby code to find the team associated with the user. Replace api-team_5 with the username of the service account you are investigating.
```
User.find_by(:username => 'api-team_5').memberships[0].team
```
The command returns the details of the associated team. In this example, the account belongs to the test-group team.
```
#<Team id: 5, organization_id: 1, name: "test-group", created_at: "2023-02-17 10:39:57.362492000 +0000">
```

Additional Information

For more details on the users endpoint, refer to the Terraform Enterprise API documentation.
To learn more about VCS providers, see the VCS Providers documentation.
For information on managing teams, refer to the Teams documentation.