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.

Sign up for GitHub

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

Updating Vault docs for JWT support of numeric bound_claims #24921

Merged
merged 3 commits into from
Jan 18, 2024
Merged

Updating Vault docs for JWT support of numeric bound_claims #24921

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
19a9d24
Add a note that the role name is available as role in entity alias me…
stefan-zh Jan 17, 2024
3a4a3c3
Update JWT docs for numeric bound_claims
stefan-zh Jan 17, 2024
e7aad72
Merge branch 'main' into docs/jwt-docs-update
stefan-zh Jan 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions website/content/api-docs/auth/jwt.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,11 @@ entities attempting to login. At least one of the bound values must be set.
- `bound_subject` `(string: <optional>)` - If set, requires that the `sub`
claim matches this value.
- `bound_claims` `(map: <optional>)` - If set, a map of claims (keys) to match against respective claim values (values).
The expected value may be a single string or a list of strings. The interpretation of the bound
Each expected value may be a string, integer, boolean or a list of strings. The interpretation of the bound
Copy link
Contributor Author

@stefan-zh stefan-zh Jan 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Here I left a list of strings instead of any other list, e.g. a list of integers. The reason is that the logic in the plugin needs additional refactoring to make it work for a list of integers, and I don't know if there is a use case for it as of now (it actually works for a list of booleans, but that doesn't seem a reasonable use case to me). It wasn't difficult to add support for single-value numeric claims, so we kept the change minimal.

Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks, makes sense to me!

claim values is configured with `bound_claims_type`. Keys support [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer)
syntax for referencing claims.
- `bound_claims_type` `(string: "string")` - Configures the interpretation of the bound_claims values.
If `"string"` (the default), the values will treated as string literals and must match exactly.
If `"string"` (the default), the values will be treated as literals and must match exactly.
Copy link
Contributor Author

@stefan-zh stefan-zh Jan 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Here bound_claims_type uses 2 kinds: string and glob. However, in reality, they are glob and non-glob. If the value is an integer or a boolean, the default interpretation (string) will work just fine. That is why I converted string literals to just literals. I don't know if this needs expanded explanation in the doc.

Copy link
Contributor

Choose a reason for hiding this comment

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

This makes sense to me -- thanks for updating this!

Copy link
Contributor

Choose a reason for hiding this comment

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

+, thanks!

If set to `"glob"`, the values will be interpreted as globs, with `*` matching any number of
characters.
- `groups_claim` `(string: <optional>)` - The claim to use to uniquely identify
Expand Down
3 changes: 2 additions & 1 deletion website/content/docs/auth/jwt/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -339,7 +339,8 @@ This specifies that the value in the JWT claim "division" should be copied to th
"department" claim value will also be copied into metadata but will retain the key name. If a claim is configured in `claim_mappings`,
it must existing in the JWT or else the authentication will fail.

Note: the metadata key name "role" is reserved and may not be used for claim mappings.
Note: the metadata key name "role" is reserved and may not be used for claim mappings. Since Vault 1.16 the role name is available
by the key `role` in the alias metadata of the entity after a successful login.
Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks for including this.


### Claim specifications and JSON pointer

Expand Down