Permission model

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

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

The permissions model is split into organization-level, project-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 (refer to Organization Permissions below)
• Manage agents (refer to Organization Permissions below)
• Manage organization permissions (refer to Organization Permissions below)
• Manage all organization settings (owners only)
• Manage organization billing (owners only, not applicable to Terraform Enterprise)
• Delete organization (owners only)

This list is not necessarily exhaustive.

Workspace Permissions

Most of HCP Terraform's permissions system is focused on workspaces. In general, administrators want to delegate access to specific collections of infrastructure; HCP Terraform 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, the run access plan permission 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.

• Run access:

  • Read: — 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.
  • Plan: — Implies permission to read. 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: — Implies permission to plan. Allows users to approve and apply Terraform plans, causing changes to real infrastructure.

• Variable access:

  • No access: — No access is granted to the values of Terraform variables and environment variables for the workspace.
  • Read: — 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: — Implies permission to read. Allows users to edit the values of variables in the workspace.

• State access:

  • No access: — No access is granted to the state file from the workspace.

  • Read outputs only: — 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: — Implies permission to read outputs only. 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: — Implies permission to read. Allows users to directly create new state versions in the workspace. Applying a remote Terraform run creates 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 to use any of the Terraform CLI's state manipulation and maintenance commands against this workspace, including terraform import, terraform taint, and the various terraform state subcommands.

• Other controls:

  • 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. HCP Terraform creates Run Tasks at the organization level, where you can manually associate or dissociate them with specific workspaces.
  • Lock/unlock workspace: — Allows users to manually lock the workspace to temporarily prevent runs. When a workspace's execution mode is set to "local", users must have this permission to perform local CLI runs using the workspace's state.

Fixed Permission Sets

Fixed permission sets are bundles of specific permissions for workspaces, which you can use to delegate access to workspaces easily.

Each permissions set targets a level of authority and responsibility for a given workspace's infrastructure. A permission set can grant permissions that recipients do not require but offer a balance of simplicity and utility.

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 with the Secret visibility option enabled 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.

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:

• Run access - Apply
• Variable access - Read and write
• State access - Read and write
• Other access - Lock/unlock workspace
• Other access - Download Sentinel mocks

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:

• Run access - Plan
• Variable access - Read
• State access - Read

See General Workspace Permissions above for details about specific permissions.

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 aren't responsible for maintaining that infrastructure. Read access grants the following workspace permissions:

• Run access - Read
• Variable access - Read
• State access - Read

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.

Implied Permissions

Some permissions imply other permissions. For example, permission to update a project also grants permission to read a project.

If an action states that it requires a specific permission level, you can perform that action if your permissions imply the stated permission level.

General Project Permissions

You can grant the following project permissions to teams on a per-project basis. You can grant these with either fixed permission sets or custom project permissions.

• Project access:
  • Read: — Allows users to view information about the project including the name.
  • Update: — Implies permission to read. Allows users to update the project name.
  • Delete: — Implies permission to update. Allows users to delete the project.
  • Create Workspaces: — Allow users to create workspaces in the project. This grants read access to all workspaces in the project.
  • Delete Workspaces: — Allows users to delete workspaces in the project.
    • 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.
  • Move Workspaces: — Allows users to move workspaces out of the project. A user must have this permission on both the source and destination project to successfully move a workspace from one project to another.
• Team management:
  • None: — No access to view teams assigned to the project.
  • Read: — Allows users to see teams assigned to the project for visible teams.
  • Manage: — Implies permission to read. Allows users to set or remove project permissions for visible teams. Project admins can not view or manage secret teams unless they are also organization owners.

See General Workspace Permissionsfor the complete list of available permissions for a project's workspaces.

Fixed Permission Sets

Fixed permission sets are bundles of specific permissions for projects, which you can use to delegate access to a project's workspaces easily.

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 with admin permissions on a project are dubbed that project's "project admins".

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.

Custom Project Permissions

Custom permissions enable you to assign specific and granular permissions to a team. You can use custom permission sets to create task-focused permission sets and control sensitive information.

You can create a set of custom permissions using any of the permissions listed under General Project Permissions.

Some permissions, such as the project access permission, are tiered. You can only assign one permission per category because higher-level permissions include the capabilities of lower levels.

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 Agent Pools

Allows members to create, edit, and delete agent pools within their organization.

This permission implicitly grants access to read all workspaces, which is necessary for agent pool management.

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.

Team Management Permissions

HCP Terraform has three levels of team management permissions: manage membership, manage teams, and manage organization access. Each permission level grants users the ability to perform specific actions and each progressively requires prerequisite permissions.

For example, to grant a user the manage teams permission, that user must already have manage membership permissions. To grant a user the manage organization access permission, a user must have both manage teams and manage membership permissions.

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.

Manage Teams

Allows members to create, update, and delete teams, and generate, regenerate, and revoke tokens.

This permission grants the ability to update a team's names, SSO IDs, and token management permissions, but does not allow access to organization settings. On its own, this permission does not allow users to create, update, delete, or otherwise access secret teams.

The manage teams permission confers all permissions granted by the manage membership permission.

This permission allows owners of large organizations to delegate team management to another trusted team. You should only grant it to teams of trusted users.

Manage Organization Access

Allows members to update a team's organization access settings.

On its own, this permission does not allow users to create, update, delete, or otherwise access secret teams. This permission confers all of the permissions granted by the manage teams and manage membership permissions.

This permission allows owners of large organizations to delegate team management to another trusted team. You should only grant it to teams of trusted users.

Include Secret Teams

Allows members access to secret teams at the level permitted by that user's team permissions setting.

This permission acts as a modifier to existing team management permissions. Members with this permission can access secret teams up to the level permitted by other team management permissions. For example, if a user has permission to include secret teams and manage teams, that user can create secret teams.

Allow Member Token Management

Allows owners and members with manage teams permissions to enable and disable team token management for team members. This permission defaults to true.

When member token management is enabled, members will be able to perform actions on team tokens, including generating and revoking a team token.

When member token management is disabled, members will be unable to perform actions on team tokens, including generating and revoking a team token.

Permissions Outside HCP Terraform's Scope

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

Since HCP Terraform integrates with other systems, the permissions models of those systems can also be relevant to the overall security model of your HCP Terraform 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 HCP Terraform organization. (And when auto-apply is enabled, merging changes will indirectly apply runs.)
• If you use HCP Terraform'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 HCP Terraform 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 HCP Terraform 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.