Permissions overview

To control access in HCP Terraform organizations, add users to a team and grant the team permissions to perform actions, such as creating or updating one or more projects or workspaces.

If you are in a HashiCorp Cloud Platform (HCP) Europe organization, you can manage user access and permissions through HCP groups and roles and then further refine those permissions with HCP Terraform roles. To learn more, refer to HCP group roles and HCP Terraform permissions.

Effective permissions

The HCP Terraform permissions model is split into three scopes. You can set permissions at the following scopes:

Each permission is additive, granting a user the highest level of permissions possible, regardless of which scope set that permission. A team's effective permissions is the sum of the permissions that team has from every permission level.

The scope that you grant a permission does not matter, the level of access that the permission grants determines what a user can do.

For example, a team has Manage all workspaces permission for an organization, and the Read role in a workspace, then the team has Manage all workspaces permissions for the workspace. HCP Terraform grants Manage all workspaces on that workspace because it is the most permissive level of access.

Conversely, a team's organization permission does not override their workspace permission. For example, the View all workspaces permission set for an organization does not override the Write role set on a specific workspace.

We recommend following the principle of least privilege when configuring permissions. Only grant users the permissions necessary to access the resources they need for their job function.

Set permissions

To learn how to set permissions for organizations, projects, and workspaces, refer to Set permissions.

HCP group roles and HCP Terraform permissions

In an HashiCorp Cloud Platform (HCP) Europe organization, you manage user access through groups. To learn more about HCP Europe, refer to Use HCP Terraform in Europe. To learn how to set up groups and assign users to them in HCP, refer to Groups.

You can assign permissions to groups in the following ways:

HCP roles: You can assign HCP roles to groups in HCP, and those roles automatically grant permissions in HCP Terraform.
HCP Terraform roles: Assign additional permissions at the organization, project, and workspace level to further refine group access in HCP Terraform.

We recommend following the principle of least privilege when configuring roles. HCP roles grant permissions in HCP Terraform and other HCP services. If a group only needs to manage resources in HCP Terraform, assign roles in HCP Terraform and refrain from granting more permissive HCP roles.

For example, to allow a user to view all workspaces in an organization in HCP Terraform, you could assign the View all workspaces permission in HCP Terraform at the organization-level, instead of the more permissive Viewer role in HCP.

To learn how to set HCP Terraform roles for groups at the organization, project, and workspace level, refer to Set permissions.

Permissions Outside HCP Terraform's Scope

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

The permissions models of systems you integrate with HCP Terraform can affect the overall security of your HCP Terraform organization. Consider the following examples:

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. When auto-apply is enabled, merging changes indirectly start runs.
If you use HCP Terraform's API to create a Slack bot for provisioning infrastructure, anyone who is 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 run 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.