diff --git a/website/content/api-docs/auth/jwt.mdx b/website/content/api-docs/auth/jwt.mdx index 4b99126ef80d..531b472bc913 100644 --- a/website/content/api-docs/auth/jwt.mdx +++ b/website/content/api-docs/auth/jwt.mdx @@ -112,8 +112,8 @@ entities attempting to login. At least one of the bound values must be set. - `name` `(string: )` - Name of the role. - `role_type` `(string: )` - Type of role, either "oidc" (default) or "jwt". - `bound_audiences` `(array: )` - List of `aud` claims to match against. - Any match is sufficient. For "jwt" roles, at least one of `bound_audiences`, `bound_subject`, - `bound_claims` or `token_bound_cidrs` is required. Optional for "oidc" roles. + Any match is sufficient. Required for "jwt" roles if the JWT has an `aud` + claim. Optional for "oidc" roles. - `user_claim` `(string: )` - The claim to use to uniquely identify the user; this will be used as the name for the Identity entity alias created due to a successful login. The claim value must be a string. diff --git a/website/content/docs/auth/jwt/index.mdx b/website/content/docs/auth/jwt/index.mdx index f46495876775..12746e776fa9 100644 --- a/website/content/docs/auth/jwt/index.mdx +++ b/website/content/docs/auth/jwt/index.mdx @@ -178,8 +178,9 @@ only needs to validate the provided JWT. ### JWT verification -JWT signatures will be verified against public keys from the issuer. This process can be done in -three different ways, though only one method may be configured for a single backend: +Vault verifies JWT signatures against public keys from the issuer. You can +only configure one JWT signature verification method per mounted backend from +the following options: - **Static Keys**. A set of public keys is stored directly in the backend configuration. See the [jwt_validation_pubkeys](/vault/api-docs/auth/jwt#jwt_validation_pubkeys) @@ -201,8 +202,15 @@ three different ways, though only one method may be configured for a single back and [oidc_discovery_ca_pem](/vault/api-docs/auth/jwt#oidc_discovery_ca_pem) configuration options. -If multiple methods are needed, another instance of the backend can be mounted and configured -at a different path. + +To configure additional verification methods, you must mount and configure one +backend instance per method at different paths. + +After verifying the JWT signatures, Vault checks the corresponding `aud` claim. + +If the JWT in the authentication request contains an `aud` claim, the +associated `bound_audiences` for the role must match at least one of the `aud` +claims declared for the JWT. ### Via the CLI @@ -308,10 +316,13 @@ management tool. Once a JWT has been validated as being properly signed and not expired, the authorization flow will validate that any configured "bound" parameters match. In some cases there are dedicated parameters, for example `bound_subject`, -which must match the JWT's `sub` parameter. A role may also be configured to -check arbitrary claims through the `bound_claims` map. The map contains a set -of claims and their required values. For example, assume `bound_claims` is set -to: +that must match the provided `sub` claim. For roles of type "jwt": + +1. the `bound_audiences` parameter is required when an `aud` claim is set. +1. the `bound_audiences` parameter must match at least one of provided `aud` claims. + +You can also configure roles to check an arbitrary set of claims and required +values with the `bound_claims` map. For example, assume `bound_claims` is set to: ```json { diff --git a/website/content/docs/upgrading/upgrade-to-1.17.x.mdx b/website/content/docs/upgrading/upgrade-to-1.17.x.mdx index ad1e02deb986..e9fee91aef15 100644 --- a/website/content/docs/upgrading/upgrade-to-1.17.x.mdx +++ b/website/content/docs/upgrading/upgrade-to-1.17.x.mdx @@ -68,6 +68,18 @@ protection is a beta feature in 1.17.0 and is disabled by default. The beta request limiter will be removed from Vault entirely in a later release. +### JWT auth login requires bound audiences on the role + +The `bound_audiences` parameter of "jwt" roles **must** match at least one of +the JWT's associated `aud` claims. The `aud` claim claim can be a single string +or a list of strings as per [RFC 7519 Section 4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). +If the JWT's `aud` claim is not set, then the role's `bound_audiences` +parameter is not required. + +Users may not be able to log into Vault if the JWT role is configured +incorrectly. For additional details, refer to the +[JWT auth method (API)](/vault/api-docs/auth/jwt) documentation. + ## Known issues and workarounds @include 'known-issues/ocsp-redirect.mdx' diff --git a/website/content/partials/known-issues/1_16-jwt_auth_bound_audiences.mdx b/website/content/partials/known-issues/1_16-jwt_auth_bound_audiences.mdx new file mode 100644 index 000000000000..629eed95fe3a --- /dev/null +++ b/website/content/partials/known-issues/1_16-jwt_auth_bound_audiences.mdx @@ -0,0 +1,32 @@ +### JWT auth login requires bound audiences on the role + +#### Affected versions + +- 1.15.9 +- 1.15.10 +- 1.16.3 +- 1.16.4 + +#### Issue +A behavior change was made in the jwt auth plugin to address CVE-2024-5798. +Since the behavior change was a breaking change, we reverted the change in +the versions after 1.15.10 and 1.16.4. However, the behavior change will go +into effect in 1.17. + +The new behavior requires that the `bound_audiences` parameter of "jwt" roles +**must** match at least one of the JWT's associated `aud` claims. The `aud` +claim can be a single string or a list of strings as per +[RFC 7519 Section 4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). + +Users may not be able to log into Vault if the JWT role is configured +incorrectly. For additional details, refer to the +[JWT auth method (API)](/vault/api-docs/auth/jwt) documentation. + +See this [issue](https://github.com/hashicorp/vault/issues/27343) for more details. + +#### Workaround + +Configure the `bound_audiences` parameter of "jwt" roles to match at least one +of the JWT's associated `aud` claims. This configuratoin will be required for +1.17 and later. +