Security

Terraform Cloud security model

Purpose of this document

This document explains the security model of Terraform Cloud and the security controls available to end users. Additionally, it provides best practices for securely managing your infrastructure with Terraform Cloud.

Important concepts

Projects, workspaces, and teams

Terraform Cloud organizes infrastructure with workspaces. Workspaces represent a logical security boundary within the organization. Variables, state, SSH keys, and log output are local to a workspace. You can grant teams read, plan, write, admin, or a customized set of permissions within a workspace.

Projects let you group related workspaces in your organization. You can use projects to assign read, write, maintain, admin, or a customized set of permissions to a particular team which grants specific permissions to all workspaces in the project.

Terraform runs - plans and applies

Terraform Cloud will provision infrastructure according to your Terraform configuration which you can upload through the VCS-driven, API-driven, or CLI-driven workflows. You can read more about the different workflows here. It’s important to note that Terraform Cloud performs all Terraform operations within the same privilege context. Both the plan and apply operations have access to the full workspace variables, state versions, and Terraform configuration.

Terraform state file

Terraform Cloud retains the current and all historical state versions for each workspace. Depending on the resources that are used in your Terraform configuration, these state versions may contain sensitive data such as database passwords, resource IDs, etc.

Personas

Organization owners

Members of the owners team have administrator-level privileges within an organization. Members of this team will have access to workspaces, projects, and settings within the organization. This role is intended for users who will perform administrative tasks in your organization.

Workspace and project team members

Teams let you group users within an organization. You can grant teams read, plan, write, admin, or a customized set of permissions, each of which allow them to perform various functions within the workspace. You can also grant teams read, write, maintain, admin, or a customized set of permissions for a project, which grants specific permissions to any workspaces in that project. At a higher level, you can use organization-level privileges, which apply to projects and workspaces across the organization.

Contributors to connected VCS repositories

Terraform Cloud executes Terraform configuration from connected VCS repositories. Depending on the configuration, Terraform Cloud may automatically trigger Terraform operations when the connected repositories receive new contributions.

Authorization model

Workspaces provide a logical security boundary within the organization. Environment variables and Terraform configurations are isolated within a workspace, and access to a workspace is granted on a per-team basis.

All organizations in Terraform Cloud contain an “owners” team, which grants admin-level access to the organization and all its workspaces.

All workspaces in an organization belong to a project. You can grant teams read, write, maintain, admin, or a customized set of permissions for the project, which grants specific permissions on on all workspaces within the project. You can also grant teams read, plan, write, admin, or a customized set of permissions for a specific workspace. It’s important to note that, from a security perspective, the plan permission is equivalent to the write permission. The plan permission is provided to protect against accidental Terraform runs but is not intended to stop malicious actors from accessing sensitive data within a workspace. Terraform plan and apply operations can execute arbitrary code within the ephemeral build environment. Both of these operations happen in the same security context with access to the full set of workspace variables, Terraform configuration, and Terraform state.

By default, Teams with read privileges within a workspace can view the workspace's state. You can remove this access by using customized workspace permissions; however, this will only apply to state file access through the API or UI. Terraform must access the state file in order to perform plan and apply operations, so any user with the ability to upload Terraform configurations and initiate runs will transitively have access to the workspaces' state.

State may be shared across workspaces via the remote state access workspace setting.

Terraform configuration files in connected VCS repositories are inherently trusted. Commits to connected repositories will automatically queue a plan within the corresponding workspace. Pull requests to connected repositories will initiate a speculative plan, though this behavior may be disabled via the speculative plan setting on the workspace settings page. Terraform Cloud has no knowledge of your VCS's authorization controls and does not associate Terraform Cloud user accounts with VCS user accounts — the two should be considered separate identities.

Threat model

Terraform Cloud is designed to execute Terraform operations and manage the state file to ensure that infrastructure is reliably created, updated, and destroyed by multiple users of an organization.

The following are part of the Terraform Cloud threat model:

Confidentiality and integrity of communication between Terraform clients and Terraform Cloud

All communication between clients and Terraform Cloud is encrypted end-to-end using TLS. Terraform Cloud currently supports TLS version 1.2. Terraform Cloud communicates with linked VCS repositories using the Oauth2 authorization protocol. Terraform Cloud can also be configured to fetch Terraform modules from private repositories using the SSH protocol with a customer-provided private key.

Confidentiality of state versions, Terraform configurations, and stored variables

As a user, you will entrust Terraform Cloud with information that is very sensitive to your organization such as API tokens, your Terraform configurations, and your Terraform state file. Terraform Cloud is designed to ensure the confidentiality of this information, it relies on Vault Transit for encrypting workspace variables. Terraform configurations and state are encrypted at rest with uniquely derived encryption keys backed by Vault. You can view how all customer data is encrypted and stored on our data security page.

Enforcement of authentication and authorization policies for data access and actions taken through the UI or API

Terraform Cloud enforces authorization checks for all actions taken within the API or through the UI. More information about Terraform Cloud workspace-level and organization level permission are available here.

Isolation of Terraform executions

Each Terraform operation (plan and apply) happens in an ephemeral environment that is created immediately before the run and destroyed after it is completed. The build environment is designed to provide isolation between Terraform executions and between Terraform Cloud tenants.

Reliability and availability of Terraform Cloud

Terraform Cloud is spread across multiple availability zones for reliability, we perform regular backups of our production data stores and have a process for recovering in case of a major outage.

What isn’t part of the threat model

Malicious contributions to Terraform configuration in VCS repositories

Commits and pull requests to connected VCS repositories will trigger a plan operation within the workspace. Terraform Cloud does not perform any authentication or authorization checks against commits in linked VCS repositories, and cannot prevent malicious Terraform configuration from exfiltrating sensitive data during plan operations. For this reason, it is important to restrict access to connected VCS repositories. Speculative plans for pull requests may be disabled on the workspace settings page.

Note: Terraform Cloud will not automatically trigger plans for pull requests from forked repositories.

Malicious Terraform providers or modules

Terraform providers and modules used in your Terraform configuration will have full access to the variables and Terraform state within a workspace. Terraform Cloud cannot prevent malicious providers and modules from exfiltrating this sensitive data. We recommend only using trusted modules and providers within your Terraform configuration.

Malicious bypasses of Terraform policies

The policy-as-code frameworks used by the Terraform Policy Enforcement feature are embedded within Terraform Cloud and can be used to ensure the infrastructure provisioned using Terraform complies with defined organizational policies. The goal of this feature is to enforce compliance with organizational policies and best practices when provisioning infrastructure using Terraform.

It is important to note that the policy-as-code integration in Terraform Cloud should be viewed as a guide or set of guardrails, not a security boundary. It is not designed to prevent malicious actors from executing malicious Terraform configurations or modifying infrastructure.

Malicious or insecure third-party run tasks

Terraform Run Tasks are provided with access to all Terraform configuration and plan data. Terraform Cloud does not have the capability to prevent malicious Run Tasks from potentially exfiltrating sensitive data that may be present in either the Terraform configuration or plan.

In order to minimize potential security risks, it is highly recommended to only utilize trusted technology partners for Run Tasks within your Terraform organization and limit the number of users who have been assigned the Manage Run Tasks permission.

Access to sensitive variables or state from Terraform operations

Marking a variable as “sensitive” will prevent it from being displayed in the UI, but will not prevent it from being read by Terraform during plan or apply operations. Similarly, customized workspace permissions allow you to restrict access to workspace state via the UI and API, but will not prevent it from being read during Terraform operations.

Redaction of sensitive variables in Terraform logs

The logs from a Terraform plan or apply operation are visible to any user with at least “read” level access in the associated workspace. While Terraform tries to avoid writing sensitive information to logs, redactions are best-effort. This feature should not be treated as a security boundary, but instead as a mechanism to mitigate accidental exposure. Additionally, Terraform Cloud is unable to protect against malicious users who attempt to use Terraform logs to exfiltrate sensitive data.

Recommendations for securely using Terraform Cloud

Enforce strong authentication

Terraform Cloud supports two factor authentication via SMS or TOTP. Organizations can configure mandatory 2FA for all members in the organization settings. Organizations may choose to configure SSO for their organization.

Minimize the number of users in the owners team

Users of the owners team will have full access to all workspaces within the organization. If SSO is enabled, members of the “Owners” team will still be able to authenticate with their username and password. This group should be reserved for only a small number of administrators, and membership should be audited periodically.

Apply the principle of least privilege to workspace membership

Teams allow you to group users and assign them various privileges within workspaces. We recommend applying the principle of least privilege when creating teams and assigning permissions so that each user within your organization has the minimum required privileges.

Protect API keys

Terraform Cloud allows you to create user, team, and organization API tokens. You should take care to store these tokens securely, and rotate them periodically. Vault users can leverage the Terraform Cloud Secret backend, which allows you to generate ephemeral tokens.

Control access to source code

By default, commits and pull requests to connected VCS repositories will automatically trigger a plan operation in a Terraform Cloud workspace. Terraform Cloud cannot protect against malicious code in linked repositories, so you should take care to only grant trusted operators access to these repositories. Workspaces may be configured to enable or disable speculative plans for pull requests to linked repositories. You should disable this setting if you allow untrusted users to open pull requests in connected VCS repositories.

Note: Terraform Cloud will not automatically trigger plans for pull requests from forked repositories.

Restrict access to workspace state

Workspaces may be configured to share their state with other workspaces within the organization or globally with the entire organization via the remote state setting. Because workspace state may contain sensitive information, we recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other.

Use separate agent pools for sensitive workspaces

Terraform Cloud Agents can be shared across all workspaces within an organization or scoped to specific workspaces. If agent pools are shared among multiple workspaces, a malicious actor in one of those workspaces could exfiltrate the agent’s API token, access private resources from the perspective of the agent, or modify the agent’s environment, potentially impacting other workspaces. For this reason, we creating separate agent pools for sensitive workspaces and using the agent scoping setting to restrict which workspaces can target each agent pool.

Treat Archivist URLs as secrets

Terraform Cloud uses a blob storage service called Archivist for storing various pieces of customer data. Archivist URLs (which have the origin https://archivist.terraform.io) are returned by various Terraform Cloud APIs, such as the state versions API. Unlike the rest of Terraform Cloud’s API, Archivist’s API does not require the user to submit a Bearer Token with each request. Instead, Archivist URLs contain a signed short term authorization token that is used to perform authorization checks. For this reason, Archivist URLs must be treated as secrets and should not be logged or shared.

Use dynamic credentials

Storing static credentials in Terraform Cloud increases the inherent risk of a malicious user or a compromised plan or apply operation exposing your credentials. Because static credentials are usually long-lived and exposed in many locations, they are troublesome to revoke and replace.

Using dynamic provider credentials eliminates the need to store static credentials in Terraform Cloud, reducing the risk of exposure. Dynamic provider credentials generate new temporary credentials for each operation and expire after that operation completes.