[ NEEDS REWRITE ]
OIDC allows workflows to authenticate and interact with HashiCorp Vault using short-lived tokens. This eliminates the need for long-lived tokens or static credentials, providing a more secure and manageable approach to accessing secrets directly from GitHub Actions.
Configuration: You configure your Vault server to trust GitHub as an external identity provider by setting up a role for JWT-based authentication. This involves specifying details such as the issuer URL and configuring the Vault role with appropriate policies.
Authentication Flow: GitHub Actions workflows use the GitHub-provided JWT token to authenticate with Vault. Vault validates the token against the GitHub OIDC issuer and verifies claims like repository, branch, or environment. Upon successful validation, Vault issues a Vault token with permissions specified in the configured policies.
vault auth enable jwt
vault write auth/jwt/role/github-actions bound_issuer=https://token.actions.githubusercontent.com user_claim=repository bound_claims_format=glob bound_claims={"repository":"<your_org_or_repo>/*"} token_policies=github-actions-policy ttl=1h
path "some/path/github/sub/folder/*" {
capabilities = ["read"]
}
VAULT_ADDR: The URL of your Vault server.VAULT_ROLE: The name of the Vault role (e.g., github-actions).VAULT_NAMESPACE (if applicable): Your Vault namespace.name: Retrieve Secret from Vault with OIDC
on:
workflow_dispatch:
jobs:
oidc-to-vault:
runs-on: ubuntu-latest
permissions:
id-token: write # Required for requesting the JWT
contents: read # Default read permissions
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Authenticate with Vault and Retrieve Secret
id: vault
uses: hashicorp/vault-action@3.1.0
with:
url: $
method: oidc
role: $
secrets: |
github_token=some/path/github/sub/folder/read-access-file:github_token
- name: Use the Retrieved Secret
run: |
echo "GitHub Token: $GITHUB_TOKEN"
env:
GITHUB_TOKEN: $
bound_claims.Vault supports OIDC authentication, allowing GitHub Actions to authenticate dynamically.
vault auth enable jwt
Replace YOUR_GITHUB_ORG and YOUR_REPO_NAME with your actual values.
vault write auth/jwt/config \
oidc_discovery_url="https://token.actions.githubusercontent.com" \
bound_issuer="https://token.actions.githubusercontent.com"
vault write auth/jwt/role/github-actions \
bound_audiences="sts.amazonaws.com" \
bound_claims="repository=YOUR_GITHUB_ORG/YOUR_REPO_NAME" \
policies="github-read-access" \
user_claim="repository" \
ttl="1h"
Create a policy file (github-read.hcl):
path "secret/data/github" {
capabilities = ["read"]
}
Apply the policy:
vault policy write github-read-access github-read.hcl
GitHub Actions can now authenticate with Vault using OIDC.
Update your GitHub Actions workflow (``):
jobs:
checkout-all-repos:
runs-on: ubuntu-latest
permissions:
id-token: write # Required for OIDC authentication
contents: read
steps:
- name: Authenticate with Vault via OIDC
id: vault-auth
run: |
export VAULT_ADDR="https://your-vault-server.com"
VAULT_TOKEN=$(curl --request POST --data \
'{"role": "github-actions", "jwt": "'"$(cat /token/github_oidc_token)"'"}' \
$VAULT_ADDR/v1/auth/jwt/login | jq -r '.auth.client_token')
echo "::add-mask::$VAULT_TOKEN"
echo "VAULT_TOKEN=$VAULT_TOKEN" >> $GITHUB_ENV
- name: Fetch GitHub Token from Vault
run: |
GH_TOKEN=$(curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/secret/data/github | jq -r '.data.data.org_read_token')
echo "::add-mask::$GH_TOKEN"
echo "GH_TOKEN=$GH_TOKEN" >> $GITHUB_ENV
- name: List all repositories
run: |
curl -H "Authorization: token $GH_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/orgs/YOUR_GITHUB_ORG/repos
To connect to HashiCorp Vault from GitHub Actions using OIDC (OpenID Connect), you can leverage the hashicorp/vault-action to simplify the process. OIDC allows your workflow to authenticate to Vault without managing long-lived credentials, making it secure and ideal for CI/CD pipelines.
Example Vault policy and role configuration:
# Create an OIDC role for GitHub Actions
vault write auth/jwt/role/github-actions \
bound_issuer=https://token.actions.githubusercontent.com \
user_claim=repository \
bound_claims_format=glob \
bound_claims={"repository":"<your_org_or_repo>/*"} \
token_policies=github-actions-policy \
ttl=1h
# Define the policy to grant access
vault policy write github-actions-policy - <<EOF
path "some/path/github/sub/folder/*" {
capabilities = ["read"]
}
EOF
https://token.actions.githubusercontent.com.jwt auth method in Vault:
vault auth enable jwt
Below is an example GitHub Actions workflow to authenticate to Vault using OIDC:
name: Retrieve Secret from Vault with OIDC
on:
workflow_dispatch:
jobs:
oidc-to-vault:
runs-on: ubuntu-latest
permissions:
id-token: write # Required for OIDC
contents: read # Default read permissions
steps:
# Step 1: Set up Vault OIDC Authentication and Retrieve Secret
- name: Authenticate with Vault and Retrieve Secret
id: vault
uses: hashicorp/vault-action@3.1.0
with:
url: https://vault.example.com
method: oidc
role: github-actions
secrets: |
github_token=some/path/github/sub/folder/read-access-file:github_token
# Step 2: Use the Retrieved Secret
- name: Use the secret
run: |
echo "GitHub Token: $GITHUB_TOKEN"
env:
GITHUB_TOKEN: $
permissions block, set:
permissions:
id-token: write
This allows GitHub Actions to request an OIDC token to authenticate with Vault.
hashicorp/vault-action Configuration:
method: oidc input specifies OIDC authentication.role: github-actions maps to the Vault role created earlier (auth/jwt/role/github-actions).https://token.actions.githubusercontent.com) and uses it to authenticate with Vault.To recap, ensure the following is configured in Vault:
vault auth enable jwt
vault write auth/jwt/role/github-actions \
bound_issuer=https://token.actions.githubusercontent.com \
user_claim=repository \
bound_claims_format=glob \
bound_claims={"repository":"<your_org_or_repo>/*"} \
token_policies=github-actions-policy \
ttl=1h
path "some/path/github/sub/folder/*" {
capabilities = ["read"]
}
bound_claims.