Service principals

This topic describes the steps to use service principals to authenticate service requests from applications, hosted services, and automated tools on the HashiCorp Cloud Platform (HCP).

Service principals can only be associated with one organization, and you can assign role-based permissions to service principals so that they can perform specific actions in HCP. Refer to the user permissions for details.

Types of service principals

Create service principals as organization-level or project-level. This section gives an overview of both types, explains how to create each type, and how to delete each type.

To use service principals, you must also create a corresponding service principal key. Refer to service principal keys for more information.

Organization-level service principals

Organization-level service principals are scoped to interact with every resource and project within an organization. For example, an organization-level service principal with viewer permissions can view all resources across all projects within an organization.

Project-level service principals

Project-level service principals are designed to interact with resources within a specific project in an organization. By default, they can only access resources in the project where they were created.

You can grant project-level service principals additional permissions by assigning them roles in other projects or at the organization level. This allows a single project-level service principal to manage resources across multiple projects or even perform organization-wide actions, such as creating new projects.

This capability is especially important for automated workflows using workload identity federation, which requires project-level service principals. By assigning organization-level roles (like Project Creator or Group Admin) to a project-level service principal, you can automate your entire HCP infrastructure without needing long-lived, organization-level static keys.

Example:

Imagine a project-level service principal named automation-sp that was created in the Dev-Infra project.

It could have the Contributor role in its home Dev-Infra project.
It could be assigned the Viewer role in the Prod-Infra project, allowing it to read production resources without being able to change them (via cross-project role assignment).
It could also be assigned the organization-level Project Creator role, allowing it to provision new projects for development teams via an automation script using workload identity federation.

In this scenario, a single project-level service principal has a flexible combination of permissions across the organization, all while adhering to the principle of least privilege.

You must use project-level service principals when configuring workload identity federation.

Create a service principal

Follow similar steps to create organization-level and project-level service principals.

Organization-level service principals

Log into the HCP portal and choose your organization.
Click Access control (IAM).
Click Service principals.
Click Create service principal.
Enter a service principal name. Then select the desired organization role for the service principal.
Click Create service principal.

Use the hcp iam service-principals create command to create the service principal.

The following example creates a service principal named example-sp.

$ hcp iam service-principals create iam/organization/d3e891e7-35c5-4ffb-a192-567e02ec566f/service-principal/example-sp

Use the hcp_service_principal resource.

data "hcp_organization" "my_org" {
}

resource "hcp_service_principal" "example" {
  name   = "workload-sp"
  parent = data.hcp_organization.my_org.resource_name
}

Project-level service principals

Log into the HCP portal and choose your organization.
Click Projects and then select the project you want to create a service principal in.
Click Access control (IAM).
Click Service principals.
Click Create service principal.
Enter a service principal name. Then select the desired scope and role for the service principal.
Click Create service principal.

Use the hcp iam service-principals create command to create the service principal.

The following example creates a project-level service principal named example-sp.

$ hcp iam service-principals create iam/project/d3e891e7-35c5-4ffb-a192-567e02ec566f/service-principal/example-sp

Use the hcp_service_principal resource.

resource "hcp_project" "my_proj" {
  name = "platform-dev"
}

resource "hcp_service_principal" "example" {
  name   = "workload-sp"
  parent = hcp_project.my_proj.resource_name
}

Cross project service principals

Create a service principal in a project as shown above.
Select the other project you want to give the service principal access to
Click Access control (IAM).
Click Add new assignment.
Search for the service principal by name or by ID in the search box. Searching by name will show a dropdown of all service principals from the organization and all projects within the organization that contain that name.
Select the service principal from the dropdown list.
Select the service role to assign to the service principal from the two dropdown lists: Select service and Select role(s).
Click Save.
The service principal will be listed in the role assignments list with an icon, which when hovered over, shows a Cross-project tag.

Use the hcp_service_principal resource.

resource "hcp_project" "first_project" {
  name = "example-first-project"
}

resource "hcp_service_principal" "sp" {
  name   = "example-first-project-sp"
  parent = hcp_project.first_project.resource_name
}

resource "hcp_project" "second_project" {
  name = "example-second-project"
}

resource "hcp_project_iam_binding" "example" {
  project_id   = hcp_project.second_project.resource_id
  principal_id = hcp_service_principal.sp.resource_id
  role         = "roles/contributor"
}

Delete a service principal

Follow similar steps to delete organization-level and project-level service principals.

Before you can delete a service principal, you must delete all keys associated with it.

Organization-level service principals

Log into the HCP portal and choose your organization.
Click Access control (IAM).
Click Service principals.
Click on the dropdown next to the specific service principal you want to delete.
Click Delete service principal.
Type DELETE in the prompted field and click Delete.

Use the hcp iam service-principals delete command to delete a service principal.

The following example deletes a service principal named example-sp.

$ hcp iam service-principals delete iam/organization/d3e891e7-35c5-4ffb-a192-567e02ec566f/service-principal/example-sp

Project-level service principals

Log into the HCP portal and choose your organization.
Click Projects and select the desired project to create a service principal in.
Click Access control (IAM).
Click Service principals.
Click on the dropdown next to the specific service principal you want to delete.
Click Delete service principal.
Type DELETE in the prompted field and click Delete.

Use the hcp iam service-principals delete command to delete a service principal.

The following example deletes a project-level service principal named example-sp.

$ hcp iam service-principals delete iam/project/d3e891e7-35c5-4ffb-a192-567e02ec566f/service-principal/example-sp