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. However, these service principals can be assigned roles in additional projects beyond their original scope.

When a project-level service principal is assigned a role in another project, it can interact with the resources in that project according to the permissions granted by the assigned role. The service principal will retain its default permissions in its original project while gaining the new permissions in the additional project.

Example:

A service principal created with viewer permissions in Project A can be assigned contributor permissions in Project B. In this scenario:

The service principal will only have view access to the resources in Project A (its original project).
It will have contributor access to the resources in Project B (the additional project).

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