Update docs with GitHub OIDC token configuration (#301)

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 }}
+                token: ${{ secrets.VAULT_TOKEN }}
-                caCertificate: ${{ secrets.VAULTCA }}
+                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
-...
+jobs:
-with:
+    retrieve-secret:
-  url: https://vault.mycompany.com:8200
+        permissions:
-  token: ${{ secrets.VaultToken }}
+            contents: read
-  caCertificate: ${{ secrets.VAULTCA }}
+            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 }}
+  roleId: ${{ secrets.VAULT_ROLE_ID }}
-  secretId: ${{ secrets.secretId }}
+  secretId: ${{ secrets.VAULT_SECRET_ID }}
-  caCertificate: ${{ secrets.VAULTCA }}
 ```
-- **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 }}
+  githubToken: ${{ secrets.GITHUB_TOKEN }}
-  caCertificate: ${{ secrets.VAULTCA }}
 ```
-- **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
+  role: <Vault JWT Auth Role Name>
-```
-
-**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
   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.VAULT_TOKEN }}
-        token: ${{ secrets.VaultToken }}
+        namespace: admin
-        namespace: ns1
         secrets: |
             secret/ci/aws accessKey | AWS_ACCESS_KEY_ID ;
             secret/ci/aws secretKey | AWS_SECRET_ACCESS_KEY ;