Permissions

Hands-on: Try the Manage Permissions in Terraform Cloud tutorial.

Terraform Cloud's access model is team-based. In order to perform an action within a Terraform Cloud organization, users must belong to a team that has been granted the appropriate permissions.

The permissions model is split into organization-level and workspace-level permissions. Additionally, every organization has a special team named "owners", whose members have maximal permissions within the organization.

Organization Owners

Every organization has a special "owners" team. Members of this team are often referred to as "organization owners".

Organization owners have every available permission within the organization. This includes all organization-level permissions, and the highest level of workspace permissions on every workspace.

There are also some actions within an organization that are only available to owners. These are generally actions that affect the permissions and membership of other teams, or are otherwise fundamental to the organization's security and integrity.

Permissions for the owners team include:

• Manage workspaces (refer to Organization Permissions below; equivalent to admin permissions on every workspace)
• Manage policies (refer to Organization Permissions below)
• Manage policy overrides (refer to Organization Permissions below)
• Manage VCS settings (refer to Organization Permissions below)
• Manage the private registry (refer to Organization Permissions below)
• Invite users to organization (owners only)
• Manage team membership (owners only)
• View all secret teams (owners only)
• Manage organization permissions (owners only)
• Manage all organization settings (owners only)
• Manage organization billing (owners only, not applicable to Terraform Enterprise)
• Delete organization (owners only)
• Manage agents (owners only)

This list is not necessarily exhaustive.

Workspace Permissions

Most of Terraform Cloud's permissions system is focused on workspaces. In general, administrators want to delegate access to specific collections of infrastructure; Terraform Cloud implements this by granting permissions to teams on a per-workspace basis.

There are two ways to choose which permissions a given team has on a workspace: fixed permission sets, and custom permissions. Additionally, there is a special "admin" permission set that grants the highest level of permissions on a workspace.

Implied Permissions

Some permissions imply other permissions; for example, permission to queue plans also grants permission to read runs.

If documentation or UI text states that an action requires a specific permission, it is also available for any permission that implies that permission.

General Workspace Permissions

The following workspace permissions can be granted to teams on a per-workspace basis. They can be granted via either fixed permission sets or custom workspace permissions.

• Runs:

  • Read runs: — Allows users to view information about remote Terraform runs, including the run history, the status of runs, the log output of each stage of a run (plan, apply, cost estimation, policy check), and configuration versions associated with a run.
  • Queue plans: — Implies permission to read runs. Allows users to queue Terraform plans in a workspace, including both speculative plans and normal plans. Normal plans must be approved by a user with permission to apply runs. This also allows users to comment on runs.
  • Apply runs: — Implies permission to queue plans. Allows users to approve and apply Terraform plans, causing changes to real infrastructure.

• Lock and unlock workspace: — Allows users to manually lock the workspace to temporarily prevent runs. When a workspace's execution mode is set to "local", this permission is required for performing local CLI runs using this workspace's state.

• Download Sentinel mocks: — Allows users to download data from runs in the workspace in a format that can be used for developing Sentinel policies. This run data is very detailed, and often contains unredacted sensitive information.

• Manage Workspace Run Tasks: - Allows users to associate or dissociate run tasks with the workspace. Run Tasks are created at the organization level, after which you can manually associate or dissociate them with specific workspaces.

• Variables:

  • Read variables: — Allows users to view the values of Terraform variables and environment variables for the workspace. Note that variables marked as sensitive are write-only, and can't be viewed by any user.
  • Read and write variables: — Implies permission to read variables. Allows users to edit the values of variables in the workspace.

• State versions:

  • Read state outputs: — Allows users to access values in the workspace's most recent Terraform state that have been explicitly marked as public outputs. Output values are often used as an interface between separate workspaces that manage loosely coupled collections of infrastructure, so their contents can be relevant to people who have no direct responsibility for the managed infrastructure but still indirectly use some of its functions. This permission is required to access the State Version Outputs API endpoint.

    Note: Read state versions permission is required to use the terraform output command or the terraform_remote_state data source against the workspace.

  • Read state versions: — Implies permission to read state outputs. Allows users to read complete state files from the workspace. State files are useful for identifying infrastructure changes over time, but often contain sensitive information.

  • Read and write state versions: — Implies permission to read state versions. Allows users to directly create new state versions in the workspace. Applying a remote Terraform run will create new state versions without this permission, but if the workspace's execution mode is set to "local", this permission is required for performing local runs. This permission is also required for using any of Terraform CLI's state manipulation and maintenance commands against this workspace, including terraform import, terraform taint, and the various terraform state subcommands.

Workspace Admins

Much like the owners team has full control over an organization, each workspace has a special "admin" permissions level that grants full control over the workspace. Members of a team with admin permissions on a workspace are sometimes called "workspace admins" for that workspace.

Admin permissions include the highest level of general permissions for the workspace. There are also some permissions that are only available to workspace admins, which generally involve changing the workspace's settings or setting access levels for other teams.

Workspace admins have all General Workspace Permissions, as well as the ability to do the following tasks:

• Read and write workspace settings. This includes general settings, notification configurations, run triggers, and more.
• Set or remove workspace permissions for visible teams. Workspace admins cannot view or manage teams that are are Secret, unless they are also organization owners.
• Delete the workspace

Fixed Permission Sets

Fixed permission sets are bundles of specific permissions on a workspace, designed for basic patterns of delegated access.

Each of these groups of permissions is designed around a target level of authority and responsibility for a given workspace's infrastructure. They can sometimes grant permissions that their recipients do not need, but they try to strike a balance of simplicity and utility.

Read

The "read" permission set is for people who need to view information about the status and configuration of managed infrastructure in order to do their jobs, but who aren't responsible for maintaining that infrastructure. Read access grants the following workspace permissions:

• Read runs
• Read variables
• Read state versions

See General Workspace Permissions above for details about specific permissions.

Plan

The "plan" permission set is for people who might propose changes to managed infrastructure, but whose proposed changes should be approved before they are applied. Plan access grants the following workspace permissions:

• Queue plans
• Read variables
• Read state versions

See General Workspace Permissions above for details about specific permissions.

Write

The "write" permission set is for people who do most of the day-to-day work of provisioning and modifying managed infrastructure. Write access grants the following workspace permissions:

• Apply runs
• Lock and unlock workspace
• Download Sentinel mocks
• Read and write variables
• Read and write state versions
• Manage workspace run tasks

See General Workspace Permissions above for details about specific permissions.

Custom Workspace Permissions

Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. This enables more task-focused permission sets and tighter control of sensitive information.

You can use custom permissions to assign any of the permissions listed above under General Workspace Permissions, with the exception of admin-only permissions.

The minimum custom permissions set for a workspace is the permission to read runs; the only way to grant a team lower access is to not add them to the workspace at all.

Some permissions - such as the runs permission - are tiered: you can assign one permission per category, since higher permissions include all of the capabilities of the lower ones.

Organization Permissions

Separate from workspace permissions, teams can be granted permissions to manage certain resources or settings across an organization. To set these permissions for a team, click Settings in the top navigation bar. Then click Teams and select the team name from the list.

The following organization permissions are available:

Manage Policies

Allows members to create, edit, and delete the organization's Sentinel policies.

This permission implicitly gives permission to read runs on all workspaces, which is necessary to set enforcement of policy sets.

Manage Run Tasks

Allows members to create, edit, and delete run tasks on the organization.

Manage Policy Overrides

Allows members to override soft-mandatory policy checks.

This permission implicitly gives permission to read runs on all workspaces, which is necessary to override policy checks.

Manage Workspaces

Allows members to create and administrate all workspaces within the organization. This grants the following abilities:

• Admin access to all workspaces. Any action that requires admin access is also available to teams with permission to manage workspaces.
• The ability to create new workspaces (otherwise only available to organization owners).
• Create, update, and delete Variable Sets

Manage VCS Settings

Allows members to manage the set of VCS providers and SSH keys available within the organization.

Manage Private Registry

Allows members to publish and delete providers, modules, or both providers and modules in the organization's private registry. These permissions are otherwise only available to organization owners.

Permissions Outside Terraform Cloud's Scope

This documentation only refers to permissions that are managed by Terraform Cloud itself.

Since Terraform Cloud integrates with other systems, the permissions models of those systems can also be relevant to the overall security model of your Terraform Cloud organization. For example:

• When a workspace is connected to a VCS repository, anyone who can merge changes to that repository's main branch can indirectly queue plans in that workspace, regardless of whether they have explicit permission to queue plans or are even a member of your Terraform Cloud organization. (And when auto-apply is enabled, merging changes will indirectly apply runs.)
• If you use Terraform Cloud's API to create a Slack bot for provisioning infrastructure, anyone able to issue commands to that Slack bot can implicitly act with that bot's permissions, regardless of their own membership and permissions in the Terraform Cloud organization.
• When a run task sends a request to an integrator, it provides an access token that provides access depending on the run task stage:
  • For post-plan, it provides access to the runs plan json and the run task callback
  • All access tokens created for run tasks have a lifetime of 10 minutes

When integrating Terraform Cloud with other systems, you are responsible for understanding the effects on your organization's security. An integrated system is able to delegate any level of access that it has been granted, so carefully consider the conditions and events that will cause it to delegate that access.