diff --git a/website/content/api-docs/auth/azure.mdx b/website/content/api-docs/auth/azure.mdx index 3f8eef4e2a..98ebc9f2c9 100644 --- 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: "")` - 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)` - 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. diff --git a/website/content/api-docs/secret/azure.mdx b/website/content/api-docs/secret/azure.mdx index 4c5d202a43..70e95c34c5 100644 --- 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: "")` - 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)` - 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 diff --git a/website/content/docs/auth/azure.mdx b/website/content/docs/auth/azure.mdx index dae629a2ed..e6e3487975 100644 --- 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) + + + +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::auth:`. + 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. diff --git a/website/content/docs/secrets/azure.mdx b/website/content/docs/secrets/azure.mdx index 0e3eedb058..96a1956dd4 100644 --- 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) + + + +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::secret:`. + 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