Configuring OpenID Connect in HashiCorp Vault

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to authenticate with a HashiCorp Vault to retrieve secrets.

This guide gives an overview of how to configure HashiCorp Vault to trust GitHub's OIDC as a federated identity, and demonstrates how to use this configuration in the hashicorp/vault-action action to retrieve secrets from HashiCorp Vault.

Prerequisites

• To learn the basic concepts of how GitHub uses OpenID Connect (OIDC), and its architecture and benefits, see "About security hardening with OpenID Connect."

• Before proceeding, you must plan your security strategy to ensure that access tokens are only allocated in a predictable way. To control how your cloud provider issues access tokens, you must define at least one condition, so that untrusted repositories can’t request access tokens for your cloud resources. For more information, see "Configuring the OIDC trust with the cloud."

Adding the identity provider to HashiCorp Vault

To use OIDC with HashiCorp Vault, you will need to add a trust configuration for the GitHub OIDC provider. For more information, see the HashiCorp Vault documentation.

Configure the vault to accept JSON Web Tokens (JWT) for authentication:

• For the oidc_discovery_url, use https://token.actions.githubusercontent.com
• For bound_issuer, use https://token.actions.githubusercontent.com
• Ensure that bound_subject is correctly defined for your security requirements. For more information, see "Configuring the OIDC trust with the cloud" and hashicorp/vault-action.

Updating your GitHub Actions workflow

To update your workflows for OIDC, you will need to make two changes to your YAML:

1. Add permissions settings for the token.
2. Use the hashicorp/vault-action action to exchange the OIDC token (JWT) for a cloud access token.

To add OIDC integration to your workflows that allow them to access secrets in Vault, you will need to add the following code changes:

• Grant permission to fetch the token from the GitHub OIDC provider:
  • The workflow needs permissions: settings with the id-token value set to write. This lets you fetch the OIDC token from every job in the workflow.
• Request the JWT from the GitHub OIDC provider, and present it to HashiCorp Vault to receive an access token:
  • You could use the Actions toolkit to fetch the tokens for your job, or you can use the hashicorp/vault-action action to fetch the JWT and receive the access token from the Vault.

This example demonstrates how to use OIDC with the official action to request a secret from HashiCorp Vault.

Adding permissions settings

 The job or workflow run requires a permissions setting with id-token: write. You won't be able to request the OIDC JWT ID token if the permissions setting for id-token is set to read or none.

The id-token: write setting allows the JWT to be requested from GitHub's OIDC provider using one of these approaches:

• Using environment variables on the runner (ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN).
• Using getIDToken() from the Actions toolkit.

If you only need to fetch an OIDC token for a single job, then this permission can be set within that job. For example:

permissions:
  id-token: write

You may need to specify additional permissions here, depending on your workflow's requirements.

Requesting the access token

The hashicorp/vault-action action receives a JWT from the GitHub OIDC provider, and then requests an access token from your HashiCorp Vault instance to retrieve secrets. For more information, see the HashiCorp Vault documentation.

This example demonstrates how to create a job that requests a secret from HashiCorp Vault.

• <Vault URL>: Replace this with the URL of your HashiCorp Vault.
• <Role name>: Replace this with the role you've set in the HashiCorp Vault trust relationship.
• <Audience>: Replace this with the audience you've defined in the HashiCorp Vault trust relationship.
• <Secret-Path>: Replace this with the path to the secret you're retrieving from HashiCorp Vault. For example: secret/data/ci npmToken.

jobs:
    retrieve-secret:
        steps:
            - name: Retrieve secret from Vault
              uses: hashicorp/vault-action@v2.4.0
              with:
                url: <Vault URL>
                role: <Role name>
                method: jwt
                jwtGithubAudience: <Audience>
                secrets: <Secret-Path>
                
            - name: Use secret from Vault
               run: |
                 # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.