Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: correct auth jwt role requirements #27384

Merged
merged 10 commits into from
Jun 12, 2024
5 changes: 2 additions & 3 deletions website/content/api-docs/auth/jwt.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -111,9 +111,8 @@ entities attempting to login. At least one of the bound values must be set.

- `name` `(string: <required>)` - Name of the role.
- `role_type` `(string: <optional>)` - Type of role, either "oidc" (default) or "jwt".
- `bound_audiences` `(array: <optional>)` - 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: <required>)` - List of `aud` claims to match against.
Any match is sufficient. Required for "jwt" roles, optional for "oidc" roles.
- `user_claim` `(string: <required>)` - 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.
Expand Down
24 changes: 16 additions & 8 deletions website/content/docs/auth/jwt/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:
fairclothjm marked this conversation as resolved.
Show resolved Hide resolved

- **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)
Expand All @@ -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

Expand Down Expand Up @@ -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
{
Expand Down
13 changes: 13 additions & 0 deletions website/content/docs/upgrading/upgrade-to-1.16.x.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

@thyton thyton Jun 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ignore token `aud` claims that were not a list of strings.
ignore token `aud` claims that were not a list of strings. Starting from 1.16.3,
it would ignore token `aud` claims that are not a single audience string or a list of strings.

I think we should state what changed from 1.16.3. My wording might be confusing here.

Copy link
Contributor Author

@fairclothjm fairclothjm Jun 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the previous sentence makes that clear. Maybe we can get the education team's input on this? That said, I think your wording should say something like

Starting from 1.16.3, token aud claims can be a single string or a list of strings and they must match at least one of the role's bound_audiences.

But then maybe the next paragraph should be reworked?

cc @schavis

Copy link
Contributor

@thyton thyton Jun 7, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think saying this could be misleading.

Starting from 1.16.3, token aud claims can be a single string or a list of strings

The value type of aud in JWT claims follows the specification of JWT, which changed to allow string type independently prior to 1.16.3. I believe users had been sending login requests with single string aud. We didn't include that type into our invalidation logic until 1.16.3.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, how about I change the wording of the paragraph to this:

JWT auth roles of type "jwt" require the bound_audiences claim to match at
least one of the JWT's aud claims. The JWT's aud claim can be a single string
or a list of strings as per RFC 7519 Section 4.1.3. 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'
Expand Down
Loading