From 91ff3725243d931f74ccfa11436edd76de8793ff Mon Sep 17 00:00:00 2001 From: JM Faircloth Date: Thu, 6 Jun 2024 10:54:29 -0500 Subject: [PATCH] docs: correct auth jwt role requirements --- website/content/api-docs/auth/jwt.mdx | 5 ++-- website/content/docs/auth/jwt/index.mdx | 24 ++++++++++++------- .../docs/upgrading/upgrade-to-1.16.x.mdx | 13 ++++++++++ 3 files changed, 31 insertions(+), 11 deletions(-) diff --git a/website/content/api-docs/auth/jwt.mdx b/website/content/api-docs/auth/jwt.mdx index 4b99126ef80d..3e214055a69b 100644 --- a/website/content/api-docs/auth/jwt.mdx +++ b/website/content/api-docs/auth/jwt.mdx @@ -111,9 +111,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. +- `bound_audiences` `(array: )` - List of `aud` claims to match against. + Any match is sufficient. Required for "jwt" roles, 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..9b5c439452f6 100644 --- a/website/content/docs/auth/jwt/index.mdx +++ b/website/content/docs/auth/jwt/index.mdx @@ -178,8 +178,13 @@ 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: +JWT signatures will be verified against public keys from the issuer. You can +configure JWT signature verifcation in several different ways, though only one +method may be configured for a single backend. If multiple methods are needed, +another instance of the backend can be mounted and configured at a different +path. + +You can configure public keys using one of the following methods: - **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 +206,9 @@ 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. +Once the JWT signatures are verified, the role's `bound_audiences` parameter is +checked. The `bound_audiences` parameter is required and must match at least +one of the `aud` claims on the JWT. ### Via the CLI @@ -308,10 +314,12 @@ 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: +which must match the JWT's `sub` claim. For roles of type "jwt", the +`bound_audiences` parameter is required and must match the JWT's `aud` claim. + +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: ```json { diff --git a/website/content/docs/upgrading/upgrade-to-1.16.x.mdx b/website/content/docs/upgrading/upgrade-to-1.16.x.mdx index 7a5d52d2d1fb..c3aa75563bb0 100644 --- a/website/content/docs/upgrading/upgrade-to-1.16.x.mdx +++ b/website/content/docs/upgrading/upgrade-to-1.16.x.mdx @@ -81,6 +81,19 @@ userattr="userprincipalname" Refer to the [LDAP auth method (API)](/vault/api-docs/auth/ldap) page for more details on the configuration. +### JWT auth login requires bound audiences on the role + +JWT auth roles of type "jwt" require the `bound_audiences` claim to match at +least one of the JWT's `aud` claims. Prior to 1.16.3, the JWT auth method would +ignore token `aud` claims that were not a list of strings. + +The consequence of not configuring this correctly means users may not be able +to login to Vault. To fix the issue, update the role's `bound_audiences` +parameter to match the `aud` claim on the JWT. + +Refer to the [JWT auth method (API)](/vault/api-docs/auth/jwt) page for +more details on the configuration. + ## Known issues and workarounds @include 'known-issues/1_16-jwt_auth_config.mdx'