Add WIF documentation for GCP Auth and Secrets engines (#27170)

Co-authored-by: Sarah Chavis <[email protected]>
hashicorp · Jun 3, 2024 · 01ccf58 · 01ccf58
1 parent 1d87ed8
commit 01ccf58
Show file tree

Hide file tree

Showing 4 changed files with 256 additions and 11 deletions.
diff --git a/website/content/api-docs/auth/gcp.mdx b/website/content/api-docs/auth/gcp.mdx
@@ -21,7 +21,25 @@ at any location, please update your API calls accordingly.
 Configures the credentials required for the plugin to perform API calls
 to Google Cloud. These credentials will be used to query the status of IAM
 entities and get service account or other Google public certificates
-to confirm signed JWTs passed in during login.
+to confirm signed JWTs passed in during login. You can configure
+credentials either with Application Credentials for a privileged service account,
+or using Plugin Workload Identity Federation (WIF).
+
+### IAM
+Vault uses the official Google Cloud SDK to source credentials from environment variables and shared files.
+
+From the highest precedence to lowest, you can pass root credentials to the Vault server in the following ways:
+
+1. Provide static credentials to the API as a payload.
+
+1. Use [plugin workload identity federation](/vault/docs/auth/gcp#plugin-workload-identity-federation-wif) credentials.
+
+1. Set [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
+as environment variables on the Vault server.
+
+<Warning title="Destructive action">
+  Passing Vault new root credentials overwrites any preexisting root credentials.
+</Warning>
 
 | Method | Path               |
 | :----- | :----------------- |
@@ -33,7 +51,18 @@ to confirm signed JWTs passed in during login.
   service account credentials file. The service account associated with the credentials
   file must have the following [permissions](/vault/docs/auth/gcp#required-gcp-permissions).
   If this value is empty, Vault will try to use [Application Default Credentials][gcp-adc]
-  from the machine on which the Vault server is running.
+  from the machine on which the Vault server is running. Mutually exclusive with `identity_token_audience`.
+
+- `service_account_email` `(string: "")` – <EnterpriseAlert product="vault" inline /> Service Account
+  to impersonate for plugin workload identity federation. Required with `identity_token_audience`.
+
+- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
+  audience claim value for plugin identity tokens. Must match an allowed audience configured
+  for the target [Workload Identity Pool](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#prepare).
+  Mutually exclusive with `credentials`.
+
+- `identity_token_ttl` `(string/int: 3600)` - <EnterpriseAlert product="vault" inline /> The
+  TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
 
 - `iam_alias` `(string: "role_id")` - Must be either `unique_id` or `role_id`.
   If `unique_id` is specified, the service account's unique ID will be used for

diff --git a/website/content/api-docs/secret/gcp.mdx b/website/content/api-docs/secret/gcp.mdx
@@ -16,18 +16,53 @@ update your API calls accordingly.
 
 ## Write config
 
+Use the endpoint to configure shared information for the secrets engine. You can configure
+credentials for a privileged service account either with Application Credentials or using
+Plugin Workload Identity Federation (WIF).
+
+### IAM
+Vault uses the official Google Cloud SDK to source credentials from environment
+variables and shared files.
+
+From the highest precedence to lowest, you can pass root credentials to the Vault
+server in the following ways:
+
+1. Provide static credentials to the API as a payload.
+
+1. Use [plugin workload identity federation](/vault/docs/secrets/gcp#plugin-workload-identity-federation-wif)
+credentials.
+
+1. Set [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
+as environment variables on the Vault server.
+
+1. Define credentials in shared credential files.
+
+<Warning title="Destructive action">
+  Passing Vault new root credential overwrites any preexisting root credentials.
+</Warning>
+
 | Method | Path          |
 | :----- | :------------ |
 | `POST` | `/gcp/config` |
 
-This endpoint configures shared information for the secrets engine.
 
 ### Parameters
 
 - `credentials` (`string:""`) - JSON credentials (either file contents or '@path/to/file')
   See docs for [alternative ways](/vault/docs/secrets/gcp#setup)
   to pass in to this parameter, as well as the
-  [required permissions](/vault/docs/secrets/gcp#required-permissions).
+  [required permissions](/vault/docs/secrets/gcp#required-permissions). Mutually exclusive with `identity_token_audience`.
+
+- `service_account_email` `(string: "")` – <EnterpriseAlert product="vault" inline /> Service Account
+to impersonate for plugin workload identity federation. Required with `identity_token_audience`.
+
+- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
+audience claim value for plugin identity tokens. Must match an allowed audience configured
+for the target [Workload Identity Pool](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#prepare).
+Mutually exclusive with `credentials`.
+
+- `identity_token_ttl` `(string/int: 3600)` - <EnterpriseAlert product="vault" inline /> The
+TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format).
 
 - `ttl` (`int: 0 || string:"0s"`) – Specifies default config TTL for long-lived credentials
   (i.e. service account keys). Uses [duration format strings](/vault/docs/concepts/duration-format).

diff --git a/website/content/docs/auth/gcp.mdx b/website/content/docs/auth/gcp.mdx
@@ -100,6 +100,41 @@ management tool.
    environment, you will additionally need to configure your environment’s custom endpoints
    via the [custom_endpoint](/vault/api-docs/auth/gcp#custom_endpoint) configuration parameter.
 
+   In some cases, you cannot set sensitive IAM security credentials in your
+   Vault configuration. For example, your organization may require that all
+   security credentials are short-lived or explicitly tied to a machine identity.
+
+   To provide IAM security credentials to Vault, we recommend using Vault
+   [plugin workload identity federation](#plugin-workload-identity-federation-wif)
+   (WIF) as shown below.
+
+1. Alternatively, configure the audience claim value and the service account email to assume for plugin workload identity federation:
+
+   ```text
+    $ vault write auth/gcp/config \
+        identity_token_audience="<TOKEN AUDIENCE>" \
+        service_account_email="<SERVICE ACCOUNT EMAIL>"
+   ```
+
+   Vault's identity token provider signs the plugin identity token JWT internally.
+   If a trust relationship exists between Vault and GCP through WIF, the auth
+   method can exchange the Vault identity token for a
+   [federated access token](https://cloud.google.com/docs/authentication/token-types#access).
+
+   To configure a trusted relationship between Vault and GCP:
+       - You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
+         for Vault.
+       - GCP must have a
+         [workload identity pool and provider](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers)
+         configured with information about the fully qualified and network-reachable
+         issuer URL for the Vault plugin's
+         [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
+
+   Establishing a trusted relationship between Vault and GCP ensures that GCP
+   can fetch JWKS
+   [public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
+   and verify the plugin identity token signature.
+
 1. Create a named role:
 
    For an `iam`-type role:
@@ -224,6 +259,61 @@ account to impersonate any service account in the GCP project where it resides.
 See [Managing service account impersonation](https://cloud.google.com/iam/docs/impersonating-service-accounts)
 for more information.
 
+## Plugin Workload Identity Federation (WIF)
+
+<EnterpriseAlert product="vault" />
+
+The GCP auth method supports the plugin WIF workflow and has a source of identity called
+a plugin identity token. A plugin identity token is a JWT that is signed internally by the Vault
+[plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration).
+
+If there is a trust relationship configured between Vault and GCP through
+[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation),
+the auth method can exchange its identity token for short-lived access tokens needed to
+perform its actions.
+
+Exchanging identity tokens for access tokens lets the GCP auth method
+operate without configuring explicit access to sensitive IAM security
+credentials.
+
+To configure the auth method to use plugin WIF:
+
+1. Ensure that Vault [openid-configuration](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-openid-configuration)
+and [public JWKS](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-public-jwks)
+APIs are network-reachable by GCP. We recommend using an API proxy or gateway
+if you need to limit Vault API exposure.
+
+1. Create a
+    [workload identity pool and provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create-pool-provider)
+    in GCP.
+    1. The provider URL **must** point at your [Vault plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration) with the
+    `/.well-known/openid-configuration` suffix removed. For example:
+    `https://host:port/v1/identity/oidc/plugins`.
+    1. Uniquely identify the recipient of the plugin identity token as the audience.
+    You can use the [default audience](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#prepare)
+    for the identity pool or a custom value less than 256 characters.
+
+1. [Authenticate a workload](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#authenticate)
+in GCP by granting the identity pool access to a dedicated service account using service account impersonation.
+Filter requests using the unique `sub` claim issued by plugin identity tokens so the GCP Auth method can
+impersonate the service account. `sub` claims have the form: `plugin-identity:<NAMESPACE>:auth:<GCP_AUTH_MOUNT_ACCESSOR>`.
+
+1. Configure the GCP auth method with the OIDC audience value and service account
+email.
+
+   ```shell-session
+   $ vault write auth/gcp/config \
+     identity_token_audience="//iam.googleapis.com/projects/410449834127/locations/global/workloadIdentityPools/vault-gcp-auth-43777a63/providers/vault-gcp-auth-wif-provider" \
+     service_account_email="vault-plugin-wif-auth@hc-b712f250b4e04cacbadd258a90b.iam.gserviceaccount.com"
+   ```
+
+Your auth method can now use plugin WIF for its configuration credentials.
+By default, WIF [credentials](https://cloud.google.com/iam/docs/workload-identity-federation#access_management)
+have a time-to-live of 1 hour and automatically refresh when they expire.
+
+Please see the [API documentation](/vault/api-docs/auth/gcp#configure)
+for more details on the fields associated with plugin WIF.
+
 ## Group aliases
 
 As of Vault 1.0, roles can specify an `add_group_aliases` boolean parameter
@@ -275,7 +365,7 @@ for IAM service accounts looks like this:
 ### GCE login
 
 GCE login only applies to roles of type `gce` and **must be completed on an
-infrastructure running on Google Cloud**. These steps will not work from your 
+infrastructure running on Google Cloud**. These steps will not work from your
 local laptop or another cloud provider.
 
 [![Vault Google Cloud GCE Login Workflow](/img/vault-gcp-gce-auth-workflow.svg)](/img/vault-gcp-gce-auth-workflow.svg)

diff --git a/website/content/docs/secrets/gcp.mdx b/website/content/docs/secrets/gcp.mdx
@@ -62,6 +62,42 @@ management tool.
     place of specifying the credentials JSON file.
     For more information on authentication, see the [authentication section](#authentication) below.
 
+    In some cases, you cannot set sensitive IAM security credentials in your
+    Vault configuration. For example, your organization may require that all
+    security credentials are short-lived or explicitly tied to a machine identity.
+
+    To provide IAM security credentials to Vault, we recommend using Vault
+    [plugin workload identity federation](#plugin-workload-identity-federation-wif)
+    (WIF) as shown below.
+
+
+1.  Alternatively, configure the audience claim value and the service account email to assume for plugin workload identity federation:
+
+    ```text
+    $ vault write gcp/config \
+        identity_token_audience="<TOKEN AUDIENCE>" \
+        service_account_email="<SERVICE ACCOUNT EMAIL>"
+    ```
+
+    Vault's identity token provider signs the plugin identity token JWT internally.
+    If a trust relationship exists between Vault and GCP through WIF, the secrets
+    engine can exchange the Vault identity token for a
+    [federated access token](https://cloud.google.com/docs/authentication/token-types#access).
+
+    To configure a trusted relationship between Vault and GCP:
+        - You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
+          for Vault.
+        - GCP must have a
+          [workload identity pool and provider](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers)
+          configured with information about the fully qualified and network-reachable
+          issuer URL for the Vault plugin's
+          [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
+
+    Establishing a trusted relationship between Vault and GCP ensures that GCP
+    can fetch JWKS
+    [public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
+    and verify the plugin identity token signature.
+
 1. Configure rolesets or static accounts. See the relevant sections below.
 
 ## Rolesets
@@ -77,11 +113,11 @@ For more information on the differences between rolesets and static accounts, se
 
 ### Roleset policy considerations
 
-Starting with Vault 1.8.0, existing permissive policies containing globs 
-for the GCP Secrets Engine may grant additional privileges due to the introduction 
+Starting with Vault 1.8.0, existing permissive policies containing globs
+for the GCP Secrets Engine may grant additional privileges due to the introduction
 of `/gcp/roleset/:roleset/token` and `/gcp/roleset/:roleset/key` endpoints.
 
-The following policy grants a user the ability to read all rolesets, but would 
+The following policy grants a user the ability to read all rolesets, but would
 also allow them to generate tokens and keys. This type of policy is not recommended:
 
 ```hcl
@@ -91,7 +127,7 @@ path "/gcp/roleset/*" {
 }
 ```
 
-The following example demonstrates how a wildcard can instead be used in a roleset policy to 
+The following example demonstrates how a wildcard can instead be used in a roleset policy to
 adhere to the principle of least privilege:
 
 ```hcl
@@ -100,7 +136,7 @@ path "/gcp/roleset/+" {
 }
 ```
 
-For more more information on policy syntax, see the 
+For more more information on policy syntax, see the
 [policy documentation](/vault/docs/concepts/policies#policy-syntax).
 
 ### Examples
@@ -217,7 +253,7 @@ Impersonated accounts are a way to generate an OAuth2 [access token](/vault/docs
 the permissions and accesses of another given service account. These access
 tokens do not have the same 10-key limit as service account keys do, yet they
 retain their short-lived nature. By default, their TTL in GCP is 1 hour, but
-this may be configured to be up to 12 hours as explained in Google's 
+this may be configured to be up to 12 hours as explained in Google's
 [short-lived credentials documentation](https://cloud.google.com/iam/docs/create-short-lived-credentials-delegated#sa-credentials-oauth).
 
 For more information regarding service account impersonation in GCP, consider starting
@@ -546,6 +582,61 @@ You can either:
   This means to update access on the dataset, Vault must be able to update the dataset's
   metadata.
 
+## Plugin Workload Identity Federation (WIF)
+
+<EnterpriseAlert product="vault" />
+
+The GCP secrets engine supports the plugin WIF workflow and has a source of identity called
+a plugin identity token. The plugin identity token is a JWT that is signed internally by Vault's
+[plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration).
+
+If there is a trust relationship configured between Vault and GCP through
+[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation),
+the secrets engine can exchange its identity token for short-lived access tokens needed to
+perform its actions.
+
+Exchanging identity tokens for access tokens lets the GCP secrets engine
+operate without configuring explicit access to sensitive IAM security
+credentials.
+
+To configure the secrets engine to use plugin WIF:
+
+1. Ensure that Vault [openid-configuration](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-openid-configuration)
+and [public JWKS](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-public-jwks)
+APIs are network-reachable by GCP. We recommend using an API proxy or gateway
+if you need to limit Vault API exposure.
+
+1. Create a
+    [workload identity pool and provider](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create-pool-provider)
+    in GCP.
+    1. The provider URL **must** point at your [Vault plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration) with the
+    `/.well-known/openid-configuration` suffix removed. For example:
+    `https://host:port/v1/identity/oidc/plugins`.
+    1. Uniquely identify the recipient of the plugin identity token as the audience.
+    You can use the [default audience](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#prepare)
+    for the identity pool or a custom value less than 256 characters.
+
+1. [Authenticate a workload](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#authenticate)
+in GCP by granting the identity pool access to a dedicated service account using service account impersonation.
+Filter requests using the unique `sub` claim issued by plugin identity tokens so the GCP Auth engine can
+impersonate the service account. `sub` claims have the form: `plugin-identity:<NAMESPACE>:secret:<GCP_SECRETS_MOUNT_ACCESSOR>`.
+
+1. Configure the GCP secrets engine with the OIDC audience value and service account
+email.
+
+   ```shell-session
+   $ vault write gcp/config \
+     identity_token_audience="//iam.googleapis.com/projects/410449834127/locations/global/workloadIdentityPools/vault-gcp-secrets-43777a63/providers/vault-gcp-secrets-wif-provider" \
+     service_account_email="vault-plugin-wif-secrets@hc-b712f250b4e04cacbadd258a90b.iam.gserviceaccount.com"
+   ```
+
+Your secrets engine can now use plugin WIF for its configuration credentials.
+By default, WIF [credentials](https://cloud.google.com/iam/docs/workload-identity-federation#access_management)
+have a time-to-live of 1 hour and automatically refresh when they expire.
+
+Please see the [API documentation](/vault/api-docs/secret/gcp#write-config)
+for more details on the fields associated with plugin WIF.
+
 ### Root credential rotation
 
 If the mount is configured with credentials directly, the credential's key may be