Skip to main content

Run the Teleport Terraform Provider with Long-Lived Credentials

Report an Issue

This guide explains how to create a Terraform user and have the Teleport Auth Service sign long-lived credentials for it. The Teleport Terraform Provider can then use those credentials to interact with Teleport.

How it works​

A Teleport administrator defines a role for the Teleport Terraform provider, as well as a role that can impersonate the Terraform provider role. A Teleport user assumes the impersonator role and executes a tctl command to instruct the Teleport Auth Service to sign a user certificate for the Terraform provider. The provider then loads the certificate in order to authenticate to your Teleport cluster and manage resources on the Teleport Auth Service backend.

warning

Long-lived credentials are less secure than other Teleport credentials and their usage is discouraged.

You must protect and rotate the credentials as they hold full Teleport administrative access. You should prefer using tbot, native Machine & Workload Identity joining in CI or Cloud environments, or create temporary bots for local use when possible.

See the list of possible Terraform provider setups to find which one fits your use-case.

Long-lived credentials are not compatible with MFA for administrative actions (MFA4A) which is an additional security layer that protects Teleport in case of Identity Provider (IdP) compromise.

Prerequisites​

  • A running Teleport cluster accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tctl and tsh clients reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

      tctl status --auth-server=teleport.example.com:3025

  • Terraform >= 1.0.0+

    terraform version
    Terraform v1.0.0

  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email@example.com to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=email@example.com
      tctl status
      Cluster  teleport.example.com
      Version  18.10.0
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Create Teleport credentials for Terraform​

Terraform needs a signed identity file from the Teleport cluster certificate authority to manage resources in the cluster. You will create a local Teleport user for this purpose.

  1. Create a folder called teleport-terraform to hold temporary files:

    mkdir -p teleport-terraform
    cd teleport-terraform

  2. Create a new file called terraform.yaml and open it in an editor.

  3. Configure settings for a local Teleport user and role by pasting the following content into the terraform.yaml file:

    kind: user
metadata:
  name: terraform
spec:
  roles: ['terraform-provider']
version: v2

    Starting with 16.2, Teleport comes with a built-in role for the Terraform provider: terraform-provider.

    RBAC for versions before v16.2

    On older versions you will need to create the Terraform role yourself. Write the following role.yaml manifest:

    kind: role
version: v7
metadata:
  name: terraform-provider
spec:
  allow:
    db_labels:
      '*': '*'
    app_labels:
      '*': '*'
    node_labels:
      '*': '*'
    rules:
      - resources:
        - app
        - cluster_auth_preference
        - cluster_networking_config
        - db
        - device
        - github
        - login_rule
        - oidc
        - okta_import_rule
        - role
        - saml
        - session_recording_config
        - token
        - trusted_cluster
        - user
        - access_list
        - node
        verbs: ['list','create','read','update','delete']

    Use tctl create -f ./role.yaml to create the role.

    These settings configure a user and role named terraform with the permissions required to manage resources in your Teleport cluster.

  4. Create the terraform user and role by running the following command:

    tctl create terraform.yaml

    The terraform user can't sign in to get credentials, so you must have another user impersonate the terraform account to request a certificate.

  5. Create a new file called terraform-impersonator.yaml and open it in an editor.

  6. Configure a role that enables your user to impersonate the Terraform user by pasting the following content into the terraform-impersonator.yaml file:

    kind: role
version: v7
metadata:
  name: terraform-impersonator
spec:
  allow:
    # This impersonate role allows any user assigned to this role to impersonate
    # and generate certificates for the user named "terraform" with a role also
    # named "terraform".
    impersonate:
      users: ['terraform']
      roles: ['terraform-provider']

  7. Create the terraform-impersonator role by running the following command:

    tctl create terraform-impersonator.yaml

  8. Assign the terraform-impersonator role to your Teleport user. The commands to run depend on how you authenticate to Teleport, that is, whether you have a local Teleport user, a single sign-on authentication connector, or a non-interactive user:

    1. Retrieve your local user's roles as a comma-separated list:

      ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')

    2. Edit your local user to add the new role:

      tctl users update $(tsh status -f json | jq -r '.active.username') \  --set-roles "${ROLES?},terraform-impersonator"

    3. Sign out of the Teleport cluster and sign in again to assume the new role.

  9. Request a signed identity file for the Terraform user by running the following command:

    tctl auth sign --user=terraform --out=terraform-identity

    After running this command, you have a terraform-identity file with credentials for the Terraform user.

Step 2/3. Prepare a Terraform configuration file​

To prepare a Terraform configuration file:

  1. Create a new file called main.tf and open it in an editor.

  2. Define an example user and role using Terraform by pasting the following content into the main.tf file, replacing teleport.example.com:443 with the host and port of the Teleport Proxy Service:

    terraform {
   required_providers {
      teleport = {
         source  = "terraform.releases.teleport.dev/gravitational/teleport"
         version = "~> 18.0"
      }
   }
}

provider "teleport" {
   addr               = 'teleport.example.com:443'
   identity_file_path = "terraform-identity"
}

# We must create a test role, if we don't declare resources, Terraform won't try to
# connect to Teleport and we won't be able to validate the setup.
resource "teleport_role" "test" {
   version = "v7"
   metadata = {
      name        = "test"
      description = "Dummy role to validate Terraform Provider setup"
      labels = {
         test = "yes"
      }
   }

   spec = {}
}

Step 3/3. Apply the configuration​

To apply the configuration:

  1. Check the contents of the teleport-terraform folder:

    ls
    main.tf  terraform-identity  terraform-impersonator.yaml  terraform.yaml

  2. Initialize the working directory that contains Terraform configuration files by running the following command:

    terraform init
    Initializing the backend...
    Initializing provider plugins...- Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ...

  3. Execute the Terraform plan defined in the configuration file by running the following command:

    terraform apply
    Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:+ create
    Terraform will perform the following actions:
    teleport_role.test will be created
    + resource "teleport_role" "test" {   + id       = (known after apply)   + kind     = (known after apply)   + metadata = {      + name      = "test"      + namespace = (known after apply)        }   + spec     = {}   + version  = "v7"     }
    Plan: 1 to add, 0 to change, 0 to destroy.

Next steps​