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
, usehttps://token.actions.githubusercontent.com
- For
bound_issuer
, usehttps://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" andhashicorp/vault-action
.
Updating your GitHub Actions workflow
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-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 theid-token
value set towrite
. 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:
- 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.
- You could use the Actions toolkit to fetch the tokens for your job, or you can use the
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
andACTIONS_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.