Federate workload identity with GitHub

This page describes how to set up workload identity federation to authenticate from a GitHub Actions Workflow using a GitHub OIDC token. 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 GitHub:

• 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 GitHub Workflow to federate access to HCP from.
• Install the HCP CLI or use the HCP Terraform Provider based on your desired configuration workflow.

Configure an external workload identity provider for GitHub

To create an HCP workload identity provider for GitHub Actions, you need a conditional access statement.

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 exchanging a GitHub OIDC token for access to HCP, the conditional access statement has access to all the claims in the token with the jwt_claims. prefix. For more information, refer to the OIDC token claim reference in the GitHub documentation.

The following example conditional access statement restricts access to HCP services to GitHub Actions that originate from acme-org/acme-repo GitHub repository.

`jwt_claims.repository == "acme-org/acme-repo"`

To restrict access further so that only requests from the Git branch main are authenticated, you can add an additional selector and value.

`jwt_claims.repository == "acme-org/acme-repo" and jwt_claims.ref == "refs/heads/main"`

For more information about using selectors and values to create compound conditional access statements, refer to conditional access statements.

Create the workload identity provider

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

$ hcp iam workload-identity-providers create-oidc <PROVIDER_NAME> \
  --service-principal=<SP_RESOURCE_NAME> \
  --issuer=https://token.actions.githubusercontent.com \
  --conditional-access='<CONDITION>' \
  --description=<DESCRIPTION>

$ hcp iam workload-identity-providers create-oidc github-example \
  --service-principal=iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-deployer \
  --issuer=https://token.actions.githubusercontent.com \
  --conditional-access='jwt_claims.repository == "acme-org/acme-repo" and jwt_claims.ref == "refs/heads/main"' \
  --description="Allow acme-repo deploy workflow to access my-app-deployer service principal"

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

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "github-example"
  service_principal = hcp_service_principal.deployment_sp.resource_name
  description       = "Allow acme-repo deploy workflow to access my-app-runtime service principal"

  oidc {
    issuer_uri = "https://token.actions.githubusercontent.com"
  }

  conditional_access = "<CONDITION>"
}

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

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "github-example"
  service_principal = hcp_service_principal.deployment_sp.resource_name
  description       = "Allow acme-repo deploy workflow to access my-app-deployer service principal"

  oidc {
    issuer_uri = "https://token.actions.githubusercontent.com"
  }

  conditional_access = "jwt_claims.repository == `acme-org/acme-repo` and jwt_claims.ref == `refs/heads/main`"
}

Configure the GitHub Actions workflow

The hashicorp/hcp-auth-action GitHub Action automatically generates a credential file during workflow execution. You can use the HCP CLI to automatically retrieve external credentials and exchange them for an HCP access token.

Add the following configuration to your GitHub Actions YAML file.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
      - id: 'Authenticate to HCP'
      - uses: 'hashicorp/hcp-auth-action@v0'
        with:
          workload_identity_provider: <PROVIDER_NAME>

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 uses the hashicorp/hcp-auth-action GitHub Action to authenticate with HCP. Then it runs the hashicorp/hcp-setup-action GitHub Action to download the HCP CLI. Finally, it uses the the HCP CLI to read a secret from HCP Vault Secrets.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
      - id: 'Authenticate to HCP'
      - uses: 'hashicorp/hcp-auth-action@v0'
        with:
          workload_identity_provider: 'GitHub'
  
      - name: 'Download hcp CLI'
        uses: 'hashicorp/hcp-setup-action@v0'
        with:
          version: 'latest'

      - name: 'Use hcp CLI to read a secret'
        run: |
          MY_SECRET=$(hcp vault-secrets secrets open \
            --app=cli --format=json foo | jq -r '.static_version.value')
          echo "::add-mask::$MY_SECRET"
          echo "MY_SECRET=$MY_SECRET" >> $GITHUB_ENV

Refer to the HCP CLI command reference for more information on commands you can use in your GitHub Actions workflows.