mirror of
https://github.com/hashicorp/vault-action.git
synced 2025-11-07 07:06:56 +00:00
Update docs with GitHub OIDC token configuration (#301)
This commit is contained in:
Rosemary Wang
GitHub
parent
67281159df
commit
876cdcfdd3
1 changed files with 156 additions and 56 deletions
212
README.md
212
README.md
|
|
@ -12,14 +12,21 @@ A helper action for easily pulling secrets from HashiCorp Vault™.
|
|||
|
||||
- [Vault GitHub Action](#vault-github-action)
|
||||
- [Example Usage](#example-usage)
|
||||
- [Authentication method](#authentication-method)
|
||||
- [Authentication Methods](#authentication-methods)
|
||||
- [JWT with GitHub OIDC Tokens](#jwt-with-github-oidc-tokens)
|
||||
- [AppRole](#approle)
|
||||
- [Token](#token)
|
||||
- [GitHub](#github)
|
||||
- [JWT with OIDC Provider](#jwt-with-oidc-provider)
|
||||
- [Kubernetes](#kubernetes)
|
||||
- [Other Auth Methods](#other-auth-methods)
|
||||
- [Key Syntax](#key-syntax)
|
||||
- [Simple Key](#simple-key)
|
||||
- [Set Output Variable Name](#set-output-variable-name)
|
||||
- [Multiple Secrets](#multiple-secrets)
|
||||
- [Other Secret Engines](#other-secret-engines)
|
||||
- [Adding Extra Headers](#adding-extra-headers)
|
||||
- [Vault Enterprise Features](#vault-enterprise-features)
|
||||
- [HashiCorp Cloud Platform or Vault Enterprise](#hashicorp-cloud-platform-or-vault-enterprise)
|
||||
- [Namespace](#namespace)
|
||||
- [Reference](#reference)
|
||||
- [Masking - Hiding Secrets from Logs](#masking---hiding-secrets-from-logs)
|
||||
|
|
@ -39,8 +46,8 @@ jobs:
|
|||
uses: hashicorp/vault-action@v2.3.1
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
token: ${{ secrets.VaultToken }}
|
||||
caCertificate: ${{ secrets.VAULTCA }}
|
||||
token: ${{ secrets.VAULT_TOKEN }}
|
||||
caCertificate: ${{ secrets.VAULT_CA_CERT }}
|
||||
secrets: |
|
||||
secret/data/ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
||||
secret/data/ci/aws secretKey | AWS_SECRET_ACCESS_KEY ;
|
||||
|
|
@ -48,87 +55,176 @@ jobs:
|
|||
# ...
|
||||
```
|
||||
|
||||
## Authentication method
|
||||
## Authentication Methods
|
||||
|
||||
While most workflows will likely use a vault token, you can also use an `approle` to authenticate with Vault. You can configure which by using the `method` parameter:
|
||||
Consider using a [Vault authentication method](https://www.vaultproject.io/docs/auth) such as the JWT auth method with
|
||||
[GitHub OIDC tokens](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) or the AppRole auth method. You can configure which by using the `method` parameter.
|
||||
|
||||
### JWT with GitHub OIDC Tokens
|
||||
|
||||
You can configure trust between a GitHub Actions workflow
|
||||
and Vault using the
|
||||
[GitHub's OIDC provider](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect).
|
||||
Each GitHub Actions workflow receives an auto-generated OIDC token with claims
|
||||
to establish the identity of the workflow.
|
||||
|
||||
__Vault Configuration__
|
||||
|
||||
<details>
|
||||
<summary>Click to toggle instructions for configuring Vault.</summary>
|
||||
|
||||
Set up Vault with the [JWT auth method](https://www.vaultproject.io/api/auth/jwt#configure).
|
||||
Pass the following parameters to your auth method configuration:
|
||||
|
||||
- `oidc_discovery_url`: `https://token.actions.githubusercontent.com`
|
||||
- `bound_issuer`: `https://token.actions.githubusercontent.com`
|
||||
|
||||
|
||||
Configure a [Vault role](https://www.vaultproject.io/api/auth/jwt#create-role) for the auth method.
|
||||
|
||||
- `role_type`: `jwt`
|
||||
|
||||
- `bound_audiences`: `"http//github.com/<org>"`. Update this parameter if
|
||||
you change the `aud` claim in the GitHub OIDC token via the
|
||||
`jwtGithubAudience` parameter in the action config.
|
||||
|
||||
- `user_claim`: Set this to a claim name (e.g., `repository`) in the
|
||||
[GitHub OIDC token](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token).
|
||||
|
||||
- `bound_claims` OR `bound_subject`: match on [GitHub subject claims](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims).
|
||||
|
||||
- For wildcard (non-exact) matches, use `bound_claims`.
|
||||
|
||||
- `bound_claims_type`: `glob`
|
||||
|
||||
- `bound_claims`: JSON object. Maps one or more claim names to corresponding wildcard values.
|
||||
```json
|
||||
{"sub": "repo:<orgName>/*"}
|
||||
```
|
||||
|
||||
- For exact matches, use `bound_subject`.
|
||||
|
||||
- `bound_claims_type`: `string`
|
||||
|
||||
- `bound_subject`: Must exactly match the `sub` claim in the OIDC token.
|
||||
```plaintext
|
||||
repo:<orgName/repoName>:ref:refs/heads/branchName
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
__GitHub Actions Workflow__
|
||||
|
||||
In the GitHub Actions workflow, the workflow needs permissions to read contents
|
||||
and write the ID token.
|
||||
|
||||
- **token**: (by default) you must provide a `token` parameter
|
||||
```yaml
|
||||
...
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
token: ${{ secrets.VaultToken }}
|
||||
caCertificate: ${{ secrets.VAULTCA }}
|
||||
jobs:
|
||||
retrieve-secret:
|
||||
permissions:
|
||||
contents: read
|
||||
id-token: write
|
||||
```
|
||||
- **approle**: you must provide a `roleId` & `secretId` parameter
|
||||
|
||||
In the action, provide the name of the Vault role you created to the `role` parameter.
|
||||
You can optionally set the `jwtGithubAudience` parameter to change the `aud`
|
||||
claim from its default.
|
||||
|
||||
```yaml
|
||||
...
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
caCertificate: ${{ secrets.VAULT_CA_CERT }}
|
||||
role: <Vault JWT Auth Role Name>
|
||||
method: jwt
|
||||
jwtGithubAudience: sigstore # set the GitHub token's aud claim
|
||||
```
|
||||
|
||||
### AppRole
|
||||
|
||||
The [AppRole auth method](https://www.vaultproject.io/docs/auth/approle) allows
|
||||
your GitHub Actions workflow to authenticate to Vault with a pre-defined role.
|
||||
Set the role ID and secret ID as GitHub secrets and pass them to the
|
||||
`roleId` and `secretId` parameters.
|
||||
|
||||
```yaml
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
caCertificate: ${{ secrets.VAULT_CA_CERT }}
|
||||
method: approle
|
||||
roleId: ${{ secrets.roleId }}
|
||||
secretId: ${{ secrets.secretId }}
|
||||
caCertificate: ${{ secrets.VAULTCA }}
|
||||
roleId: ${{ secrets.VAULT_ROLE_ID }}
|
||||
secretId: ${{ secrets.VAULT_SECRET_ID }}
|
||||
```
|
||||
- **github**: you must provide the github token as `githubToken`
|
||||
|
||||
**Notice: [Vault GitHub authentication](https://www.vaultproject.io/docs/auth/github)
|
||||
### Token
|
||||
|
||||
For the default method of authenticating to Vault,
|
||||
use a [Vault token](https://www.vaultproject.io/docs/concepts/tokens).
|
||||
Set the Vault token as a GitHub secret and pass
|
||||
it to the `token` parameter.
|
||||
|
||||
```yaml
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
caCertificate: ${{ secrets.VAULT_CA_CERT }}
|
||||
token: ${{ secrets.VAULT_TOKEN }}
|
||||
```
|
||||
|
||||
### GitHub
|
||||
|
||||
The [GitHub auth method](https://www.vaultproject.io/docs/auth/github)
|
||||
requires `read:org` permissions for authentication. The auto-generated `GITHUB_TOKEN`
|
||||
created for projects does not have these permissions and GitHub does not allow this
|
||||
token's permissions to be modified. A new GitHub Token secret must be created with
|
||||
`read:org` permissions to use this authentication method.**
|
||||
`read:org` permissions to use this authentication method.
|
||||
|
||||
Pass the GitHub token as a GitHub secret into the `githubToken` parameter.
|
||||
|
||||
```yaml
|
||||
...
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
caCertificate: ${{ secrets.VAULT_CA_CERT }}
|
||||
method: github
|
||||
githubToken: ${{ secrets.MY_GITHUB_TOKEN }}
|
||||
caCertificate: ${{ secrets.VAULTCA }}
|
||||
githubToken: ${{ secrets.GITHUB_TOKEN }}
|
||||
```
|
||||
- **jwt**: (Github OIDC) you must provide a `role` parameter, additionally you can pass `jwtGithubAudience` parameter.
|
||||
|
||||
### JWT with OIDC Provider
|
||||
|
||||
You can configure trust between your own OIDC Provider and Vault
|
||||
with the JWT auth method. Provide a `role` & `jwtPrivateKey` parameters,
|
||||
additionally you can pass `jwtKeyPassword` & `jwtTtl` parameters
|
||||
|
||||
```yaml
|
||||
...
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
caCertificate: ${{ secrets.VAULT_CA_CERT }}
|
||||
method: jwt
|
||||
role: github-action
|
||||
```
|
||||
|
||||
**Notice:** For Github provided OIDC token to work, the workflow should have `id-token: write` & `contents: read` specified in the `permissions` section of the workflow
|
||||
|
||||
```yaml
|
||||
...
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
...
|
||||
```
|
||||
|
||||
- **jwt**: you must provide a `role` & `jwtPrivateKey` parameters, additionally you can pass `jwtKeyPassword` & `jwtTtl` parameters
|
||||
|
||||
```yaml
|
||||
...
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
method: jwt
|
||||
role: github-action
|
||||
role: <Vault JWT Auth Role Name>
|
||||
jwtPrivateKey: ${{ secrets.JWT_PRIVATE_KEY }}
|
||||
jwtKeyPassword: ${{ secrets.JWT_KEY_PASS }}
|
||||
jwtTtl: 3600 # 1 hour, default value
|
||||
```
|
||||
|
||||
- **kubernetes**: you must provide the `role` paramaters. You can optionally override the `kubernetesTokenPath` paramater for custom mounted serviceAccounts. Consider [kubernetes auth](https://www.vaultproject.io/docs/auth/kubernetes) when using self-hosted runners on Kubernetes:
|
||||
### Kubernetes
|
||||
|
||||
Consider the [Kubernetes auth method](https://www.vaultproject.io/docs/auth/kubernetes)
|
||||
when using self-hosted runners on Kubernetes. You must provide the `role` parameter
|
||||
for the Vault role associated with the Kubernetes auth method.
|
||||
You can optionally override the `kubernetesTokenPath` parameter for
|
||||
custom-mounted serviceAccounts.
|
||||
|
||||
```yaml
|
||||
...
|
||||
with:
|
||||
url: https://vault.mycompany.com:8200
|
||||
caCertificate: ${{ secrets.VAULT_CA_CERT }}
|
||||
method: kubernetes
|
||||
role: ${{ secrets.KUBE_ROLE }}
|
||||
role: <Vault Kubernetes Auth Role Name>
|
||||
kubernetesTokenPath: /var/run/secrets/kubernetes.io/serviceaccount/token # default token path
|
||||
```
|
||||
|
||||
If any other method is specified and you provide an `authPayload`, the action will attempt to `POST` to `auth/${method}/login` with the provided payload and parse out the client token.
|
||||
### Other Auth Methods
|
||||
|
||||
If any other method is specified and you provide an `authPayload`, the action will
|
||||
attempt to `POST` to `auth/${method}/login` with the provided payload and parse out the client token.
|
||||
|
||||
## Key Syntax
|
||||
|
||||
|
|
@ -165,7 +261,6 @@ steps:
|
|||
# Import config...
|
||||
- name: Sensitive Operation
|
||||
run: "my-cli --token '${{ steps.secrets.outputs.npmToken }}'"
|
||||
|
||||
```
|
||||
|
||||
_**Note:** If you'd like to only use outputs and disable automatic environment variables, you can set the `exportEnv` option to `false`._
|
||||
|
|
@ -258,11 +353,16 @@ with:
|
|||
|
||||
This will automatically add the `x-secure-id` and `x-secure-secret` headers to every request to Vault.
|
||||
|
||||
## Vault Enterprise Features
|
||||
## HashiCorp Cloud Platform or Vault Enterprise
|
||||
|
||||
If you are using [HCP Vault](https://cloud.hashicorp.com/products/vault)
|
||||
or Vault Enterprise, you may need additional parameters in
|
||||
your GitHub Actions workflow.
|
||||
|
||||
### Namespace
|
||||
|
||||
If you need to retrieve secrets from a specific Vault namespace, all that's required is an additional parameter specifying the namespace.
|
||||
If you need to retrieve secrets from a specific Vault namespace, set the `namespace`
|
||||
parameter specifying the namespace. In HCP Vault, the namespace defaults to `admin`.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -271,10 +371,10 @@ steps:
|
|||
uses: hashicorp/vault-action
|
||||
with:
|
||||
url: https://vault-enterprise.mycompany.com:8200
|
||||
caCertificate: ${{ secrets.VAULT_CA_CERT }}
|
||||
method: token
|
||||
caCertificate: ${{ secrets.VAULTCA }}
|
||||
token: ${{ secrets.VaultToken }}
|
||||
namespace: ns1
|
||||
token: ${{ secrets.VAULT_TOKEN }}
|
||||
namespace: admin
|
||||
secrets: |
|
||||
secret/ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
||||
secret/ci/aws secretKey | AWS_SECRET_ACCESS_KEY ;
|
||||
|
|
|
|||
Loading…
Reference in a new issue