Federate workload identity with AWS

This page describes how to set up workload identity federation with AWS so that HCP authenticates external workloads, such as those running on EC2 or Lambda. Authenticated workloads can interact with HCP services without storing any HCP service principal keys.

Prerequisites

You must complete the following steps before configuring a workload identity provider for AWS:

You must have the Admin role on the HCP project.
Create a service principal in the desired project and grant it access to the HCP resources your workload requires.
Have access to the AWS account to federate access to HCP from.
Install the HCP CLI or use the HCP Terraform Provider based on your desired configuration workflow.

Configure a workload identity provider for AWS

To create an HCP workload identity provider for AWS, you must provide the following configuration values:

The AWS Account ID
A conditional access statement

If you do not know your AWS Account ID, refer to the AWS documentation for guidance.

Conditional access statement

When federating workload identity, one of the requirements is a conditional access statement. This statement is a boolean expression that has access to the identity claims and restricts which external identities are allowed.

When using AWS, you can access the following selectors, which correspond to the AWS GetCallerIdentity response.

aws.arn: The AWS ARN associated with the calling entity
aws.account_id: The AWS account ID number of the account that owns or contains the calling entity
aws.user_id: The unique identifier of the calling entity

To check the values of these fields, run the aws sts get-caller-identity command on the workload instance you are trying to configure.

Use these values to build a conditional access statement. The most useful attribute is aws.arn, which you format according to the following syntax:

`arn:aws:sts::<AWS_ACCOUNT_ID>:assumed-role/<AWS_IAM_ROLE>/<EC2_INSTANCE_ID>`

In the following example, 123456789012 is the AWS Account ID, my-app-role is the AWS IAM role attached to the EC2 instance, and i-00000000000000000 is the EC2 Instance ID.

`arn:aws:sts::123456789012:assumed-role/my-app-role/i-00000000000000000`

The following conditional access statement restricts access to HCP services to instances with the my-app-role IAM role attached.

`aws.arn matches “^arn:aws:sts::123456789012:assumed-role/my-app-role/”`

Create the workload identity provider

After you gather the information you need, create the workload identity provider for AWS.

Use the hcp iam workload-identity-providers create-aws command.

$ hcp iam workload-identity-providers create-aws <PROVIDER_NAME> \
  --account-id=<AWS_ACCOUNT_ID> \
  --conditional-access=<CONDITION> \
  --service-principal=<SP_RESOURCE_NAME> \
  --description=<DESCRIPTION>

This command requires the following information that is specific to your AWS and HCP accounts:

<PROVIDER_NAME>: The name of workload identity provider to create.
<AWS_ACCOUNT_ID>: The AWS Account ID that you want to allow federation from.
<CONDITION>: The conditional access statement that restricts access to the specified AWS workloads.
<SP_RESOURCE_NAME>: The service principal’s resource name, in the format iam/project/<PROJECT_ID>/service-principal/<NAME>.
<DESCRIPTION>: An optional description for the provider.

The following example creates a workload identity provider named aws-example. This provider configures HCP to restrict access to external workloads by requiring that they have the my-app-role AWS IAM role attached. Workloads that are granted access to HCP services use the my-app-runtime service principal.

$ hcp iam workload-identity-providers create-aws aws-example \
  --account-id=123456789012 \
  --conditional-access='aws.arn matches "^arn:aws:iam::123456789012:role/my-app-role/"' \
  --service-principal=iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-runtime \
  --description="Allow my-app-role on AWS to act as my-app-runtime service principal"

Use the hcp_iam_workload_identity_provider resource.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "workload_sp" {
    name = "my-app-runtime"
    }

resource "hcp_iam_workload_identity_provider" "example" {
    name              = "aws-example"
    service_principal = hcp_service_principal.workload_sp.resource_name
    description       = "Allow my-app on AWS to act as my-app-runtime service principal"

    aws {
        # Only allow workloads from this AWS Account to exchange identity
        account_id = "<AWS_ACCOUNT_ID>"
    }

    conditional_access = "<CONDITION>"
}

This configuration requires the following information that is specific to your AWS and HCP accounts:

<AWS_ACCOUNT_ID>: The AWS Account ID that you want to allow federation from.
<CONDITION>: The conditional access statement that restricts access to the specified AWS workloads.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "workload_sp" {
    name = "my-app-runtime"
    }

resource "hcp_iam_workload_identity_provider" "example" {
    name              = "aws-example"
    service_principal = hcp_service_principal.workload_sp.resource_name
    description       = "Allow my-app-role on AWS to act as my-app-runtime service principal"

    aws {
        # Only allow workloads from this AWS Account to exchange identity
        account_id = "123456789012"
    }

    # Restrict access to workloads running with "my-app-role".
    conditional_access = "aws.arn matches `^arn:aws:sts::123456789012:assumed-role/my-app-role/`"
}

Authenticate the workload's credentials

You can use the HCP CLI, HCP Terraform Provider, or HCP Go SDK to automatically retrieve external credentials and exchange them for an HCP access token. This process uses a credential file that contains the information required to obtain external credentials and the workload identity provider to exchange them with.

For more information, refer to credential files.

Create the credential file for AWS

Use the hcp iam workload-identity-providers create-cred-file command.

$ hcp iam workload-identity-providers create-cred-file <PROVIDER_NAME> \
  --aws \
  --output-file=credentials.json

This command requires the following information that is specific to your HCP account:

<PROVIDER_NAME>: The name of Workload Identity Provider to exchange credentials with, in the format iam/project/<PROJECT_ID>/service-principal/<SP_NAME>/workload-identity-provider/<PROVIDER_NAME>.

The following example creates a credentials.json file using the aws-example provider, which is associated with the my-app-runtime service principal.

$ hcp iam workload-identity-providers create-cred-file \
  iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-runtime/workload-identity-provider/aws-example \
  --aws \
  --output-file=credentials.json

If you are using IMDSv1, set the –imdsv1 flag when you run create-cred-file.

Ensure the credential file exists in the runtime environment. Because the credential file contains no secret values, you can store the credential file in the AMI, Lambda deployment package, or a container. Alternatively, you can generate it at runtime.

To use the credential file to authenticate, you can use the HCP CLI, the HCP Terraform provider, or the HCP Go SDK. Refer to use a credential file to authenticate for more information.