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 projects (refer to Organization Permissions below; equivalent to admin permissions on every project and 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)
• Manage Membership (refer to Organization Permissions below; invite or remove users from the organization itself, and manage the membership of its teams)
• 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
  • Depending on the organization's settings, workspace admins may only be able to delete the workspace if it is not actively managing infrastructure. Refer to Deleting a Workspace With Resources Under Management for details.

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

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.

Project Permissions

You can assign project-specific permissions to teams.

Fixed Permission Sets

Fixed permission sets are bundles of specific permissions for a project, designed for common usage patterns. You can only assign project-specific permissions through one of these permission sets.

Project Admin

Each project has an "admin" permissions level that grants permissions for both the project and the workspaces that belong to that project.

Members of teams with "admin" permissions for a project have General Workspace Permissions for every workspace in the project, and the ability to:

• Read and update project settings.
• Delete the project.
• Create workspaces in the project.
• Move workspaces into or out of the project. This also requires project admin permissions for the source or destination project.
• Grant or revoke project permissions for visible teams. Project admins cannot view or manage access for teams that are are Secret, unless those admins are also organization owners.

Maintain

The "maintain" permission is for people who need to manage existing infrastructure in a single project, while also granting the ability to create new workspaces in that project. Maintain access grants full control of everything in the project, including the following permissions:

• Admin access for all workspaces in this project.
• Create workspaces in this project.
• Read the project name.
• Lock and unlock all workspaces in this project.
• Read and write variables for all workspaces in this project.
• Access state for all workspaces in this project.
• Approve runs for all workspaces in this project.

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:

• Read the project name.
• Lock and unlock all workspaces in this project.
• Read and write variables for all workspaces in this project.
• Access state for all workspaces in this project.
• Approve runs for all workspaces in this project.

Read

The "read" permission set is for people who need to view information about the status and configuration of managed infrastructure for their job function, but are not responsible for maintaining that infrastructure. Read access grants the permissions to:

• Read the project name.
• Read the workspaces in the project.

Organization Permissions

Separate from project and workspace permissions, you can grant teams permissions to manage or view certain resources or settings across an organization. To set these permissions for a team, go to your organization's Settings. Then click Teams, and select the team name from the list.

The following organization permissions are available:

Project permissions

You must select a level of access for projects.

None

Members do not have access to projects or workspaces. You can grant permissions to individual projects or workspaces through Project Permissions or Workspace Permissions.

View all projects

Members can view all projects within the organization. This lets users:

• View project names in a given organization.

Manage all projects

Members can create and manage all projects and workspaces within the organization. In addition to the permissions granted by “Manage all workspaces”, this also lets users:

• Manage other teams' access to all projects.
• Create, edit, and delete projects (otherwise only available to organization owners).
• Move workspaces between projects.

Workspace permissions

You must select a level of access for workspaces.

None

Members do not have access to projects or workspaces. You can grant permissions to individual projects or workspaces through Project Permissions or Workspace Permissions.

View all workspaces

Members can view all workspaces within the organization. This lets users:

• View information and features relevant to each workspaces (e.g. runs, state versions, variables).

Manage all workspaces

Members can create and manage all workspaces within the organization. This lets users:

• Perform any action that requires admin permissions in those workspaces.
• Create new workspaces within the organization's Default Project, an action that is otherwise only available to organization owners.
• Create, update, and delete Variable Sets.

Manage Policies

Allows members to create, edit, read, list 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 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.

Manage Membership

Allows members to invite users to the organization, remove users from the organization, and add or remove users from teams within the organization.

This permission grants the ability to view the list of users within the organization, and to view the organization access of other visible teams. It does not permit the creation of teams, the ability to modify the settings of existing teams, or the ability to view secret teams.

In order to modify the membership of a team, a user with Manage Membership permissions must have visibility into the team (i.e. the team must be "Visible", or the user must be on the team). In order to remove a user from the organization, the holder of this permission must have visibility into all of the teams which the user is a member of.

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.