From fc4c7735bc8d92a26dddd4853ff5bd9c9f0e8ee1 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 20 Oct 2025 14:50:42 -0700 Subject: [PATCH 1/4] orgs page --- content/hcp-docs/content/docs/hcp/admin/orgs.mdx | 6 ++++-- content/hcp-docs/content/docs/hcp/create-account.mdx | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/hcp-docs/content/docs/hcp/admin/orgs.mdx b/content/hcp-docs/content/docs/hcp/admin/orgs.mdx index 4472e95307..9d20cc47d6 100644 --- a/content/hcp-docs/content/docs/hcp/admin/orgs.mdx +++ b/content/hcp-docs/content/docs/hcp/admin/orgs.mdx @@ -13,10 +13,12 @@ This page describes how to create and manage an organization in HashiCorp Cloud An _organization_ is a top-level entity in HCP for organizing resources. It contains one or more [HCP projects](/hcp/docs/hcp/admin/projects), which separate access to resources such as [HashiCorp Virtual Networks (HVN)](/hcp/docs/hcp/network) according to [user permissions](/hcp/docs/iam/users#user-permissions). -Users can be a member of multiple organizations if invited by the admin of other organizations. However, you can only create and own one organization for your HCP account. - An organization can have up to 100 projects. +Users can be a member of multiple organizations. + +Organizations can have a maximum of 3 users with the `owner` role. You can add and delete organization owners over time, but organizations require at least 1 owner at all times. + ## Create an organization When you sign up for a HashiCorp Cloud Platform (HCP) account, [the HCP Portal](https://portal.cloud.hashicorp.com/) takes you to a guided worfklow. diff --git a/content/hcp-docs/content/docs/hcp/create-account.mdx b/content/hcp-docs/content/docs/hcp/create-account.mdx index 6bcb6dc560..75bc008df1 100644 --- a/content/hcp-docs/content/docs/hcp/create-account.mdx +++ b/content/hcp-docs/content/docs/hcp/create-account.mdx @@ -12,7 +12,7 @@ This page explains how to create an account in HashiCorp Cloud Platform (HCP) an To meet data residency requirements, HCP requires separate accounts for the global and European geographies. -To create a global HCP account, sign up on [the HCP portal](https://portal.cloud.hashicorp.com/). To an HCP Europe account, sign up on [the HCP Europe portal](https://portal.cloud.eu.hashicorp.com/). +To create a global HCP account, sign up on [the HCP portal](https://portal.cloud.hashicorp.com/). To create an HCP Europe account, sign up on [the HCP Europe portal](https://portal.cloud.eu.hashicorp.com/). For more information, refer to [HCP Europe](/hcp/docs/hcp/europe). From 6c5990a57700a42f34602a00f9312db167663bb2 Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 20 Oct 2025 16:11:12 -0700 Subject: [PATCH 2/4] Updates --- .../hcp-docs/content/docs/hcp/admin/orgs.mdx | 22 +++++-- .../content/docs/hcp/admin/projects/index.mdx | 63 ++++++------------- .../docs/hcp/iam/access-management.mdx | 42 +++++++++---- .../hcp-docs/content/docs/hcp/iam/users.mdx | 11 ++-- .../hcp-administration/invite-users.mdx | 3 +- .../hcp-administration/permission-intro.mdx | 17 +++-- 6 files changed, 83 insertions(+), 75 deletions(-) diff --git a/content/hcp-docs/content/docs/hcp/admin/orgs.mdx b/content/hcp-docs/content/docs/hcp/admin/orgs.mdx index 9d20cc47d6..82754e0423 100644 --- a/content/hcp-docs/content/docs/hcp/admin/orgs.mdx +++ b/content/hcp-docs/content/docs/hcp/admin/orgs.mdx @@ -33,17 +33,29 @@ After you create your organization, you can [invite users to your organization]( To locate the organization ID: -1. At the bottom left, click the name of the current organization to open the organization and project selector. -1. Select an organization to open the organization's dashboard. -1. From the organization's dashboard, click **Organization settings**. +1. At the top, click the dropdown to open the organization and project selector. Select **View all organizations**. +1. Click the name of the organization. +1. From the **Organization dashboard**, click **Organization settings**. +1. Click the clipboard icon next to the ID to copy the **Organization ID**. + +## Find organization owners + +An organization can have 1-3 users with the `owner` role. Owners can change, but there must always be at least 1 owner per organization. + +To find the organization's current owners: + +1. At the top, click the dropdown to open the organization and project selector. Select **View all organizations**. +1. Click the name of the organization. +1. From the **Organization dashboard**, click **Organization settings**. 1. To copy the **Organization ID**, click the clipboard icon next to the ID. ## Manage an organization To change your organization's name: -1. Sign in to [the HCP Portal](https://portal.cloud.hashicorp.com/). -1. From the organization's dashboard, click **Organization settings**. +1. At the top, click the dropdown to open the organization and project selector. Select **View all organizations**. +1. Click the name of the organization. +1. From the **Organization dashboard**, click **Organization settings**. 1. At the top-right, click **Manage**, and then click **Rename organization**. 1. Enter a new organization name. The name must contain between 3 and 40 characters, and it may include ASCII letters, numbers, hyphens, and underscores. The name must be unique. If another organization is already using the name, you will receive a prompt to choose a different one. 1. Click **Save**. diff --git a/content/hcp-docs/content/docs/hcp/admin/projects/index.mdx b/content/hcp-docs/content/docs/hcp/admin/projects/index.mdx index 2b42ba4569..13c7672716 100644 --- a/content/hcp-docs/content/docs/hcp/admin/projects/index.mdx +++ b/content/hcp-docs/content/docs/hcp/admin/projects/index.mdx @@ -6,36 +6,26 @@ description: |- # Projects -Projects are lightweight containers for resources or use cases that require similar access. An organization contains one or more projects. HCP resources such as [HashiCorp Virtual Networks -(HVN)](/hcp/docs/hcp/network) and server clusters reside within Projects. +Projects are lightweight containers for resources or use cases that require similar access. An organization contains one or more projects. HCP resources such as [HashiCorp Virtual Networks (HVN)](/hcp/docs/hcp/network) and server clusters reside within projects. -Use projects to segment access within an organization. For example, projects can separate teams, use cases, or environments, such as development, staging, and production. The billing summary reports usage per project. +Use projects to segment access within an organization. For example, projects can separate teams, use cases, or environments, such as development, staging, and production. The billing summary reports usage per project. Here are important characteristics about HCP projects: - _Global_ [HCP service quotas](/hcp/docs/hcp/admin/support#service-quotas) remain at the - organization level and they are not enforced per project. + organization level and they are not enforced per project. Refer the [HCP Support](/hcp/docs/hcp/admin/support) page to learn more about the service quotas. - An [organization](/hcp/docs/hcp/admin/orgs) can contain 1 or more projects. - +- HCP resource names, such as a cluster name, are unique to projects. - Refer the [HCP - Support](/hcp/docs/hcp/admin/support) page to learn more about the service - quotas. - - - -- HCP resource names (e.g. cluster name) are unique per project and not per - organization. - -- You cannot deploy an HCP Vault Dedicated or HCP Consul Dedicated cluster if an - HVN belongs to a different project. +- You cannot deploy an HCP Vault Dedicated cluster if an HVN belongs to a different project. - To delete a project, all resources under the project must be deleted or - deactivated first. See the [manage resources](#manage-resources) section. + deactivated first. Refer to [manage resources](#manage-resources) for more information. + +## Use Cases -### Use Cases Taking advantage of segregating access within your organization via projects is the best way to enforce least privileged access. Deploying all HCP services or resources within one project, can lead to several unintended consequences. - Increased likelihood of over privileging identities within the project @@ -46,55 +36,42 @@ Taking advantage of segregating access within your organization via projects is Users with organization contributor, admin, or owner roles can create new projects. If an organization contributor creates a new project, the user -automatically becomes the admin of that project. (Refer to the [User -Permissions](/hcp/docs/hcp/admin/users#user-permissions) for information about -the roles you can assign.) +automatically becomes the admin of that project. Refer to the [User Permissions](/hcp/docs/hcp/admin/users#user-permissions) for information about +the roles you can assign. 1. Log into [HCP Portal](https://portal.cloud.hashicorp.com/) and choose your - organization. - - - - If you have logged in before, the portal opens the last project you were in. - Navigate back to the organization level from the breadcrumbs, or click on the - HashiCorp icon at the top-left to choose your organization. - - + organization. If you have logged in before, the portal opens the last project you were in. + Navigate to the Organization to change projects 1. Select **Projects** in the sidebar. -1. Click **+ Create project**. +1. Click **Create project**. 1. Enter the **Project name** and **Project description**. 1. Click **Create project** to complete. - ## Manage projects -Users with project admin role can edit the existing project name and -description, or delete the project. (Refer to the [User -Permissions](/hcp/docs/hcp/admin/users#user-permissions) for information about -the roles you can assign.) +Users with project owner and admin roles can edit the existing project name and +description, or delete the project. Refer to [User Permissions](/hcp/docs/hcp/admin/users#user-permissions) for information about +the roles you can assign. 1. Log into [HCP Portal](https://portal.cloud.hashicorp.com/) and choose your organization. 1. Select **Projects** in the sidebar. -1. Expand the menu next to the project you wish to modify, and select **Edit - project** to edit the project name or description, or select **Delete** to +1. Expand the menu next to the project you wish to modify. + Select **Edit project** to edit the project name or description, or select **Delete** to delete the project. - ![Projects overview](/img/docs/hcp-core/project-menu.png) - -1. Select **View project** will take you to the project setting page where you - can find the **project ID**. +1. Select **View project** to find information about the project, such as the project ID. ## Manage resources ![HCP Organization Structure](/img/docs/hcp-core/diagram-hcp_organization_project-resources.png) -A resource is any item that the access management system controls access to. Examples of resources are a HCP Vault Dedicated cluster, HCP Packer Bucket, HashiCorp Virtual Network (HVN) or a HCP Vault Secret App. The **Active Resources** page lists all resources created in the project. To delete a project, all resources must be deleted. If an resource exists, HCP will block users from deleting the project. This page helps you to identify what resources are still in the project. +A resource is any item that the access management system controls access to. Examples of resources are a HCP Vault Dedicated cluster, HCP Packer Bucket, HashiCorp Virtual Network (HVN) or a HCP Vault Secret App. The **Active Resources** page lists all resources created in the project. To delete a project, all resources must be deleted. If an resource exists, HCP will block users from deleting the project. This page helps you to identify what resources are still in the project. ![Active Resources](/img/docs/hcp-core/active-resources-page.png) \ No newline at end of file diff --git a/content/hcp-docs/content/docs/hcp/iam/access-management.mdx b/content/hcp-docs/content/docs/hcp/iam/access-management.mdx index f1edd9e209..18092e4b4d 100644 --- a/content/hcp-docs/content/docs/hcp/iam/access-management.mdx +++ b/content/hcp-docs/content/docs/hcp/iam/access-management.mdx @@ -8,16 +8,25 @@ description: |- This topic describes HCP's access management features. You can set roles and permissions at either the _organization level_ , _project level_ or _resource level_ to secure access to HCP resources. -## Roles & Permissions +## Roles and permissions @include '/hcp-administration/permission-intro.mdx' -### Organization +## Add new role assignment -The following tables describe role permissions assigned at the organization level. +Users with the `owner` role in an organization can add and assign roles at a fine-grained level using the HCP platform. - - +1. At the top, click the dropdown to open the organization and project selector. Select **View all organizations**. +1. Click the name of the organization. +1. From the **Organization dashboard**, click **Access Control (IAM)**. +1. Click **Add new assignment**. If you are not an organization's owner, this option does not appear. +1. Enter the user's email address. + +You can change the user's role assignment and the service associated with that role assignment using the drop-down menus. When you set a role assignment for all services, it sets the user's role in the organization. + +## Organization level roles and permissions + +The following table describes the roles and permissions available at the organizational level: | HCP Organization Permissions | Owner | Admin | Contributor | Viewer | Browser | No role | | --------------------------------- | :-----: | :------: | :---------: | :------: | :------: | :------: | @@ -35,7 +44,9 @@ The following tables describe role permissions assigned at the organization leve | Manage SSO configuration | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | Manage billing resources | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | - +The following tables provide additional ways to understand permissions, based on needs such as billing and SSO management. + + @@ -75,7 +86,6 @@ The following tables describe role permissions assigned at the organization leve | Manage SSO and SCIM configuration | ❌ | | Manage billing resources | ✅ | - @@ -128,7 +138,17 @@ To learn more about each permission, refer to [HCP Terraform organization permis A user can be a part of an organization with no roles assigned directly to them through the [SSO default role settings](/hcp/docs/hcp/admin/iam/sso) or IAM settings. To enforce least-privileged access, new users will have a limited experience within the platform until an Admin assigns either an organization or project role to the user. -### Project +## View current role assignments + +To view a list of current role assignments in an organization: + +1. At the top, click the dropdown to open the organization and project selector. Select **View all organizations**. +1. Click the name of the organization. +1. From the **Organization dashboard**, click **Access Control (IAM)**. + +The **Role assignments** page lists the currently assigned roles, and provides an interface to search and filter the current assignments. + +## Project level roles and permissions The following tables describe role permissions scope to the project level. @@ -227,13 +247,13 @@ To learn more about each permission, refer to [HCP Terraform project permissions -#### Assign a project role +## Assign a project role @include '/hcp-administration/assign-project-role.mdx' -# Role Names and Role IDs +## Role Names and Role IDs -To interact with the HCP Access Management system using the [HCP Terraform provider](https://registry.terraform.io/providers/hashicorp/hcp/latest) or public APIs, you must properly format the role IDs you reference.The table lists role names and the formatting of their Role IDs. +To interact with the HCP Access Management system using the [HCP Terraform provider](https://registry.terraform.io/providers/hashicorp/hcp/latest) or public APIs, you must properly format the role IDs you reference. The following able lists role names and the formatting of their Role IDs. diff --git a/content/hcp-docs/content/docs/hcp/iam/users.mdx b/content/hcp-docs/content/docs/hcp/iam/users.mdx index 05ee4b9be5..4a82ae7044 100644 --- a/content/hcp-docs/content/docs/hcp/iam/users.mdx +++ b/content/hcp-docs/content/docs/hcp/iam/users.mdx @@ -6,14 +6,14 @@ description: |- # Users +This page describes how to add users to your HashiCorp Cloud Platform (HCP) account and manage their access to resources. + +## Introduction + When you sign up for a HashiCorp Cloud Platform (HCP) account for the first -time, the HCP Portal takes you to the [create -organization](https://portal.cloud.hashicorp.com/orgs/create) page to set up -your organization. You can invite additional users to the organization so that +time, the HCP Portal takes you to the [create organization](https://portal.cloud.hashicorp.com/orgs/create) page to set up your organization. You can invite additional users to the organization so that they can access the resources. -This page describes how to add users to your HashiCorp Cloud Platform (HCP) account and manage their access to resources. - ## Invite users Use the following procedure to invite users into your organization using email. @@ -31,4 +31,5 @@ users. @include '/hcp-administration/permission-intro.mdx' ## Access Management + For more information about permissions, the different types of roles and how they can be used within HCP, checkout the [Access Management](/hcp/docs/hcp/iam/access-management) page. diff --git a/content/hcp-docs/content/partials/hcp-administration/invite-users.mdx b/content/hcp-docs/content/partials/hcp-administration/invite-users.mdx index a586006d72..31b688f1f5 100644 --- a/content/hcp-docs/content/partials/hcp-administration/invite-users.mdx +++ b/content/hcp-docs/content/partials/hcp-administration/invite-users.mdx @@ -1,8 +1,7 @@ If [Single Sign-On](/hcp/docs/hcp/iam/sso) is enabled, manage the users -through the configured identity providers instead. The option to manually invite -users as described in this section will not be available. +through the configured identity providers instead. diff --git a/content/hcp-docs/content/partials/hcp-administration/permission-intro.mdx b/content/hcp-docs/content/partials/hcp-administration/permission-intro.mdx index 94e01b2ec7..8388afcb02 100644 --- a/content/hcp-docs/content/partials/hcp-administration/permission-intro.mdx +++ b/content/hcp-docs/content/partials/hcp-administration/permission-intro.mdx @@ -1,16 +1,15 @@ -HCP uses a role-based access controls (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the specific HCP application documentation for more information. +HCP uses a role-based access controls (RBAC) system to enable members of your organizations and projects to perform actions in HCP and interact with resources. Some HCP applications allow you to assign roles for specific resources, such as an HCP Packer bucket. Refer to the individual HCP service's documentation for more information. ### Types of Roles -HCP has general grouping of roles on the platform: Basic (All services) roles and fine grained (service) roles. - -*Basic (All services) roles* contain permissions from all/most services. Consider using basic roles initially when setting up and adopting HCP. However, they should be replaced with fine-grained roles when adding production workloads. - -*Fine grained (service) roles* contain permissions from one or a minimal set of services. They are the preferred method for access management and should be leveraged over basic (All services) roles when applicable. +You can configure HCP roles for an organization at two levels: +- _Basic roles_ control permissions from all services in an organization. Basic roles are useful when you initially set up and adopt HCP, but you should replace them with fine-grained roles when adding production workloads. +- _Fine-grained roles_ control permissions for one or more services. We recommend using fine-grained roles for access management when using HCP to manage production workloads and interact with production networks. ### Inheritance -Each resource in a HCP organization has an IAM policy associated with it that informs about the level of access allowed on that resource. This IAM policy is a data structure that provides a mapping of roles to principals assigned to that resource. + +Each resource in a HCP organization has an IAM policy associated with it that sets the level of access allowed on that resource. This IAM policy is a data structure that provides a mapping of roles to principals assigned to that resource. ![Role Permission Inheritance](/img/docs/hcp-core/diagram-hcp_IAM-inheritance.png) @@ -22,6 +21,6 @@ Users inherit role permissions according to the following hierarchy: Permissions are inherited through the resource hierarchy. And they are effective for the resource they are assigned to and all of that resource's descendants. -For example, a user assigned the `viewer` role in an organization also has `viewer` role permissions for projects within the organization. Moreover, a user assigned the `contributor` role in a project also has `contributor` role permissions for resources within the project. +For example, a user assigned the `viewer` role in an organization also has `viewer` role permissions for projects within the organization. Similarly, a user assigned the `contributor` role in a project also has `contributor` role permissions for resources within the project. -If a user has an `viewer` role in an organization and `admin` role on a project in the same organization, the user receives a concatenation of `viewer` _and_ `admin` role permissions within that specific project. +If a user has an `viewer` role in an organization and `admin` role on a project in the same organization, the user receives a concatenation of `viewer` _and_ `admin` role permissions within that specific project. From 3d6ef53f1c1e142cd55051b6bf6db4824c1236e3 Mon Sep 17 00:00:00 2001 From: boruszak Date: Tue, 21 Oct 2025 13:24:50 -0700 Subject: [PATCH 3/4] Owner role ID for table --- content/hcp-docs/content/docs/hcp/iam/access-management.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/hcp-docs/content/docs/hcp/iam/access-management.mdx b/content/hcp-docs/content/docs/hcp/iam/access-management.mdx index 18092e4b4d..9eaec1bb69 100644 --- a/content/hcp-docs/content/docs/hcp/iam/access-management.mdx +++ b/content/hcp-docs/content/docs/hcp/iam/access-management.mdx @@ -260,6 +260,7 @@ To interact with the HCP Access Management system using the [HCP Terraform provi | Role name | Role ID | | ----------- | :------------------------------: | +| Owner | `roles/owner` | | Admin | `roles/admin` | | Contributor | `roles/contributor` | | Viewer | `roles/viewer` | From 35061c278692634af0d7c3e45604502f37b1a27d Mon Sep 17 00:00:00 2001 From: boruszak Date: Mon, 27 Oct 2025 16:14:57 -0700 Subject: [PATCH 4/4] Changes from review --- content/hcp-docs/content/docs/hcp/admin/orgs.mdx | 8 +++----- .../hcp-docs/content/docs/hcp/admin/projects/index.mdx | 2 +- .../hcp-docs/content/docs/hcp/iam/access-management.mdx | 8 +++++++- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/content/hcp-docs/content/docs/hcp/admin/orgs.mdx b/content/hcp-docs/content/docs/hcp/admin/orgs.mdx index 82754e0423..7329b721c4 100644 --- a/content/hcp-docs/content/docs/hcp/admin/orgs.mdx +++ b/content/hcp-docs/content/docs/hcp/admin/orgs.mdx @@ -11,13 +11,11 @@ This page describes how to create and manage an organization in HashiCorp Cloud ## Introduction An _organization_ is a top-level entity in HCP for organizing resources. It contains one or more -[HCP projects](/hcp/docs/hcp/admin/projects), which separate access to resources such as [HashiCorp Virtual Networks (HVN)](/hcp/docs/hcp/network) according to [user permissions](/hcp/docs/iam/users#user-permissions). +[HCP projects](/hcp/docs/hcp/admin/projects), which separate access to resources such as [HashiCorp Virtual Networks (HVN)](/hcp/docs/hcp/network) according to [user permissions](/hcp/docs/iam/users#user-permissions). An organization can have up to 100 projects. -An organization can have up to 100 projects. +Users can be a member of multiple organizations, and organizations can have a maximum of 3 users with the `owner` role. You can add and delete organization owners over time, but organizations require at least 1 owner at all times. -Users can be a member of multiple organizations. - -Organizations can have a maximum of 3 users with the `owner` role. You can add and delete organization owners over time, but organizations require at least 1 owner at all times. +You cannot create an organization if you are already the owner of an existing organization. ## Create an organization diff --git a/content/hcp-docs/content/docs/hcp/admin/projects/index.mdx b/content/hcp-docs/content/docs/hcp/admin/projects/index.mdx index 13c7672716..3ee2d12a31 100644 --- a/content/hcp-docs/content/docs/hcp/admin/projects/index.mdx +++ b/content/hcp-docs/content/docs/hcp/admin/projects/index.mdx @@ -72,6 +72,6 @@ the roles you can assign. ![HCP Organization Structure](/img/docs/hcp-core/diagram-hcp_organization_project-resources.png) -A resource is any item that the access management system controls access to. Examples of resources are a HCP Vault Dedicated cluster, HCP Packer Bucket, HashiCorp Virtual Network (HVN) or a HCP Vault Secret App. The **Active Resources** page lists all resources created in the project. To delete a project, all resources must be deleted. If an resource exists, HCP will block users from deleting the project. This page helps you to identify what resources are still in the project. +A resource is any item that the access management system controls access to. Examples of resources are a HCP Vault Dedicated cluster, HCP Packer Bucket, or a HashiCorp Virtual Network (HVN). The **Active Resources** page lists all resources created in the project. To delete a project, all resources must be deleted. If an resource exists, HCP will block users from deleting the project. This page helps you to identify what resources are still in the project. ![Active Resources](/img/docs/hcp-core/active-resources-page.png) \ No newline at end of file diff --git a/content/hcp-docs/content/docs/hcp/iam/access-management.mdx b/content/hcp-docs/content/docs/hcp/iam/access-management.mdx index 9eaec1bb69..14a6fb1065 100644 --- a/content/hcp-docs/content/docs/hcp/iam/access-management.mdx +++ b/content/hcp-docs/content/docs/hcp/iam/access-management.mdx @@ -14,7 +14,13 @@ This topic describes HCP's access management features. You can set roles and per ## Add new role assignment -Users with the `owner` role in an organization can add and assign roles at a fine-grained level using the HCP platform. +To assign roles at a fine-grained level using the HCP platform, users must have one of the following permissions: + +- `owner` role for the HCP organization +- `admin` role for the HCP organization +- `Organization IAM policies administrator` role + +To assign a new role: 1. At the top, click the dropdown to open the organization and project selector. Select **View all organizations**. 1. Click the name of the organization.