Add WIF documentation for Azure Auth and Secrets engines (#27185)

2025-10-29 17:52:32 +00:00 · 2024-06-03 13:17:13 -07:00
parent 01ccf580d8
commit 5acc4331ea
4 changed files with 191 additions and 1 deletions
--- a/website/content/api-docs/auth/azure.mdx
+++ b/website/content/api-docs/auth/azure.mdx
@@ -22,6 +22,9 @@ Configures the credentials required for the plugin to perform API calls
 to Azure. These credentials will be used to query the metadata about the
 virtual machine.

+You can configure the auth engine with account credentials or plugin workload
+identity federation (WIF).
+
 | Method | Path                 |
 | :----- | :------------------- |
 | `POST` | `/auth/azure/config` |
@@ -41,7 +44,14 @@ virtual machine.
  This value can also be provided with the `AZURE_CLIENT_ID` environment variable.
 - `client_secret` `(string: '')` - The client secret for credentials to query the Azure APIs.
  This value can also be provided with the `AZURE_CLIENT_SECRET` environment variable.
- `max_retries` `(int: 3)` - The maximum number of attempts a failed operation will be 
+  Mutually exclusive with `identity_token_audience`.
+- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
+  audience claim value for plugin identity tokens. Must match the allowed audiences configured
+  for the target [Federated Identity Credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app).
+  Mutually exclusive with `client_secret`.
+- `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).
+- `max_retries` `(int: 3)` - The maximum number of attempts a failed operation will be
  retried before producing an error.
 - `max_retry_delay` `(string: '60s')` - The maximum delay, in seconds, allowed before retrying an operation.
 - `retry_delay` `(string: '4s')` - The initial amount of delay, in seconds, to use before retrying an operation. Increases exponentially.
--- a/website/content/api-docs/secret/azure.mdx
+++ b/website/content/api-docs/secret/azure.mdx
@@ -20,6 +20,9 @@ Configures the credentials required for the plugin to perform API calls
 to Azure. These credentials will be used to query roles and create/delete
 service principals. Environment variables will override any parameters set in the config.

+You can configure the secrets engine with account credentials or using
+plugin workload identity federation (WIF).
+
 | Method | Path            |
 | :----- | :-------------- |
 | `POST` | `/azure/config` |
@@ -32,6 +35,13 @@ service principals. Environment variables will override any parameters set in th
  with the AZURE_CLIENT_ID environment variable. See [authentication](/vault/docs/secrets/azure#authentication) for more details.
 - `client_secret` (`string:""`) - The OAuth2 client secret to connect to Azure. This value can also be
  provided with the AZURE_CLIENT_SECRET environment variable. See [authentication](/vault/docs/secrets/azure#authentication) for more details.
+  Mutually exclusive with `identity_token_audience`.
+- `identity_token_audience` `(string: "")` - <EnterpriseAlert product="vault" inline /> The
+  audience claim value for plugin identity tokens. Must match the allowed audiences configured
+  for the target [Federated Identity Credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app).
+  Mutually exclusive with `client_secret`.
+- `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).
 - `environment` (`string:""`) - The Azure environment. This value can also be provided with the AZURE_ENVIRONMENT
  environment variable. If not specified, Vault will use Azure Public Cloud.
 - `root_password_ttl` `(string: 182d)` - Specifies how long the root password is valid for in Azure when
--- a/website/content/docs/auth/azure.mdx
+++ b/website/content/docs/auth/azure.mdx
@@ -151,6 +151,41 @@ tool.
   For the complete list of configuration options, please see the API
   documentation.

+   In some cases, you cannot set sensitive account 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 managed identity 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 Client, Tenant IDs for plugin workload identity federation:
+
+   ```text
+   $ vault write azure/config \
+       tenant_id=7cd1f227-ca67-4fc6-a1a4-9888ea7f388c \
+       client_id=dd794de4-4c6c-40b3-a930-d84cd32e9699 \
+       identity_token_audience=vault.example/v1/identity/oidc/plugins
+   ```
+
+   The Vault identity token provider signs the plugin identity token JWT internally.
+   If a trust relationship exists between Vault and Azure through WIF, the auth
+   method can exchange the Vault identity token for a federated access token.
+
+   To configure a trusted relationship between Vault and Azure:
+       - You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
+       for Vault.
+       - Azure must have a
+       [federated identity credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app)
+       configured with information about the fully qualified and network-reachable
+       issuer URL for the Vault plugin
+       [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
+
+   Establishing a trusted relationship between Vault and Azure ensures that Azure
+   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 role:

   ```shell-session
@@ -229,6 +264,55 @@ server:
 AZURE_GO_SDK_LOG_LEVEL=DEBUG
 ```

+## Plugin Workload Identity Federation (WIF)
+
+<EnterpriseAlert product="vault" />
+
+The Azure 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 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 Azure through
+[workload identity federation](https://learn.microsoft.com/en-us/entra/workload-id/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 Azure auth method
+operate without configuring explicit access to sensitive client 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 Azure. We recommend using an API proxy or gateway
+   if you need to limit Vault API exposure.
+
+1. Configure a
+   [federated identity credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app)
+   on a dedicated application registration in Azure to establish a trust relationship with Vault.
+   1. The issuer 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. The subject identifier **must** match the unique `sub` claim issued by plugin identity tokens.
+   The subject identifier should have the form `plugin-identity:<NAMESPACE>:auth:<AZURE_MOUNT_ACCESSOR>`.
+   1. The audience should be under 600 characters. The default value in Azure is `api://AzureADTokenExchange`.
+
+1. Configure the Azure auth method with the client and tenant IDs and the OIDC audience value.
+
+   ```shell-session
+   $ vault write azure/config \
+     tenant_id=7cd1f227-ca67-4fc6-a1a4-9888ea7f388c \
+     client_id=dd794de4-4c6c-40b3-a930-d84cd32e9699 \
+     identity_token_audience=vault.example/v1/identity/oidc/plugins
+   ```
+
+Your auth method can now use plugin WIF for its configuration credentials.
+By default, WIF [credentials](https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens#token-lifetime)
+have a time-to-live of 1 hour and automatically refresh when they expire.
+
+Please see the [API documentation](/vault/api-docs/auth/azure#configure)
+for more details on the fields associated with plugin WIF.
+
 ## API

 The Azure Auth Plugin has a full HTTP API. Please see the [API documentation](/vault/api-docs/auth/azure) for more details.
--- a/website/content/docs/secrets/azure.mdx
+++ b/website/content/docs/secrets/azure.mdx
@@ -61,6 +61,42 @@ management tool.
   If you are running Vault inside an Azure VM with MSI enabled, `client_id` and
   `client_secret` may be omitted. For more information on authentication, see the [authentication](#authentication) section below.

+   In some cases, you cannot set sensitive account 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 managed identity 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 Client, Tenant and Subscription IDs for plugin workload identity federation:
+
+   ```text
+   $ vault write azure/config \
+       subscription_id=$AZURE_SUBSCRIPTION_ID \
+       tenant_id=$AZURE_TENANT_ID \
+       client_id=$AZURE_CLIENT_ID \
+       identity_token_audience=$TOKEN_AUDIENCE
+   ```
+
+   The Vault identity token provider signs the plugin identity token JWT internally.
+   If a trust relationship exists between Vault and Azure through WIF, the secrets
+   engine can exchange the Vault identity token for a federated access token.
+
+   To configure a trusted relationship between Vault and Azure, :
+       - You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
+         for Vault.
+       - Azure must have a
+         [federated identity credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app)
+         configured with information about the fully qualified and network-reachable
+         issuer URL for the Vault plugin
+         [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
+
+   Establishing a trusted relationship between Vault and Azure ensures that Azure
+   can fetch JWKS
+   [public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
+   and verify the plugin identity token signature.
+
 1. Configure a role. A role may be set up with either an existing service principal, or
   a set of Azure roles that will be assigned to a dynamically created service principal.

@@ -266,6 +302,56 @@ principles it creates.
 |------------------------------------------------| ------------ | ------------------------------------------- |
 | [User Access Administrator][user_access_admin] | Subscription | Service Principal ID given in configuration |

+## Plugin Workload Identity Federation (WIF)
+
+<EnterpriseAlert product="vault" />
+
+The Azure 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 Azure through
+[workload identity federation](https://learn.microsoft.com/en-us/entra/workload-id/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 Azure secrets engine
+operate without configuring explicit access to sensitive client 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 Azure. We recommend using an API proxy or gateway
+   if you need to limit Vault API exposure.
+
+1. Configure a
+   [federated identity credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app)
+   on a dedicated application registration in Azure to establish a trust relationship with Vault.
+   1. The issuer 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. The subject identifier **must** match the unique `sub` claim issued by plugin identity tokens.
+   The subject identifier should have the form `plugin-identity:<NAMESPACE>:secret:<AZURE_MOUNT_ACCESSOR>`.
+   1. The audience should be under 600 characters. The default value in Azure is `api://AzureADTokenExchange`.
+
+1. Configure the Azure secrets engine with the subscription, client and tenant IDs and the OIDC audience value.
+
+   ```shell-session
+   $ vault write azure/config \
+     subscription_id=$AZURE_SUBSCRIPTION_ID \
+     tenant_id=$AZURE_TENANT_ID \
+     client_id=$AZURE_CLIENT_ID \
+     identity_token_audience="vault.example/v1/identity/oidc/plugins"
+   ```
+
+Your secrets engine can now use plugin WIF for its configuration credentials.
+By default, WIF [credentials](https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens#token-lifetime)
+have a time-to-live of 1 hour and automatically refresh when they expire.
+
+Please see the [API documentation](/vault/api-docs/secret/azure#configure-access)
+for more details on the fields associated with plugin WIF.
+
 ## Choosing between dynamic or existing service principals

 Dynamic service principals are preferred if the desired Azure resources can be provided