Skip to content

Commit

Permalink
docs: correct auth jwt role requirements
Browse files Browse the repository at this point in the history
  • Loading branch information
fairclothjm committed Jun 6, 2024
1 parent 15532cf commit 91ff372
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 11 deletions.
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:

- **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.

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

0 comments on commit 91ff372

Please sign in to comment.