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.
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."
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
- Ensure that
bound_subjectis correctly defined for your security requirements. For more information, see "Configuring the OIDC trust with the cloud" and
To update your workflows for OIDC, you will need to make two changes to your YAML:
- Add permissions settings for the token.
- Use the
hashicorp/vault-actionaction 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-tokenvalue set to
write. This lets you fetch the OIDC token from every job in the workflow.
- The workflow needs
- Request the JWT from the GitHub OIDC provider, and present it to HashiCorp Vault to receive an access token:
This example demonstrates how to use OIDC with the official action to request a secret from HashiCorp Vault.
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
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 (
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.
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:
jobs: retrieve-secret: steps: - name: Retrieve secret from Vault uses: email@example.com 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.