`v5` Pre-Release #234

oxisto · 2022-08-27T09:40:27Z

This commit serves as the basis for further v5 developments. It will introduce some API-breaking changes, especially to the way tokens are validated. This will allow us to provide some long-wanted features with regards to the validation API. We are aiming to do this as smoothly as possible, however, with any major version. please expect that you might need to adapt your code.

The actual development will be done in the course of the next week, if time permits. It will be done in seperate PRs that will use this PR as a base. Afterwards, we will probably merge this and release an initial 5.0.0-alpha1 or similar.

v5 Checklist:

New validation API
Cleanup / harmonize error messages
Increase code coverage

This commit serves as the basis for further `v5` developments. It will introduce some API-breaking changes, especially to the way tokens are validated. This will allow us to provide some long-wanted features with regards to the validation API. We are aiming to do this as smoothly as possible, however, with any major version. please expect that you might need to adapt your code. The actual development will be done in the course of the next week, if time permits. It will be done in seperate PRs that will use this PR as a base. Afterwards, we will probably merge this and release an initial 5.0.0-alpha1 or similar.

This PR removes the old legacy standard claims, which have been deprecated since the beginning of the `v4` module in favor of the newer `RegisteredClaims`. Removing them before any further changes to the validation API is quite useful, as less code needs to be adapated.

* New Validation API Some guidelines in designing the new validation API * Previously, the `Valid` method was placed on the claim, which was always not entirely semantically correct, since the validity is concerning the token, not the claims. Although the validity of the token is based on the processing of the claims (such as `exp`). Therefore, the function `Valid` was removed from the `Claims` interface and the single canonical way to retrieve the validity of the token is to retrieve the `Valid` property of the `Token` struct. * The previous fact was enhanced by the fact that most claims implementations had additional exported `VerifyXXX` functions, which are now removed * All validation errors should be comparable with `errors.Is` to determine, why a particular validation has failed * Developers want to adjust validation options. Popular options include: * Leeway when processing exp, nbf, iat * Not verifying `iat`, since this is actually just an informational claim. When purely looking at the standard, this should probably the default * Verifying `aud` by default, which actually the standard sort of demands. We need to see how strong we want to enforce this * Developers want to create their own claim types, mostly by embedding one of the existing types such as `RegisteredClaims`. * Sometimes there is the need to further tweak the validation of a token by checking the value of a custom claim. Previously, this was possibly by overriding `Valid`. However, this was error-prone, e.g., if the original `Valid` was not called. Therefore, we should provide an easy way for *additional* checks, without by-passing the necessary validations This leads to the following two major changes: * The `Claims` interface now represents a set of functions that return the mandatory claims represented in a token, rather than just a `Valid` function. This is also more semantically correct. * All validation tasks are offloaded to a new (optional) `validator`, which can also be configured with appropriate options. If no custom validator was supplied, a default one is used. Co-authored-by: Micah Parks <66095735+MicahParks@users.noreply.github.com>

mfridman · 2023-01-07T23:25:18Z

@oxisto Apologies, I took some time off end of December and just ran out of steam. I'd still like to work through this and get to a stable /v5, is this the right place to start reviewing?

We could also create a milestone with all the PR's and/or issues attached to it, helps differentiate with the rest of the noise.

oxisto · 2023-01-08T08:20:05Z

@oxisto Apologies, I took some time off end of December and just ran out of steam. I'd still like to work through this and get to a stable /v5, is this the right place to start reviewing?

Yes

We could also create a milestone with all the PR's and/or issues attached to it, helps differentiate with the rest of the noise.

there is a label “next” that I used to specify which PRs should end up in v5. I think we wanted to add more test coverage but from the features we are pretty much complete I would say.

go.mod

This PR adds further documentation to the validator and does an additional cleanup to make the VerifyXXX functions more managable.

MIGRATION_GUIDE.md

claims.go

map_claims.go

validator.go

Co-authored-by: Michael Fridman <mf192@icloud.com>

map_claims_test.go

oxisto · 2023-02-21T10:25:16Z

I think we are ready for a first v5.0-rc1 or something similar, @mfridman ?

mfridman · 2023-02-21T13:26:59Z

I think we are ready for a first v5.0-rc1 or something similar, @mfridman ?

Yep, this all looks great to me, kudos for getting the changes to this state.

Let's use conventional semver, exactly like so:

v5.0.0-rc.1

cc @oxisto were you going to add a tag to 148d710 and create a pre-release in GitHub?

mfridman · 2023-02-21T13:28:01Z

MIGRATION_GUIDE.md

@@ -1,4 +1,82 @@
-## Migration Guide (v4.0.0)
+# Migration Guide (v5.0.0)


Nicely documented.

Co-authored-by: Micah Parks <66095735+MicahParks@users.noreply.github.com> Co-authored-by: Michael Fridman <mf192@icloud.com>

[![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [github.com/golang-jwt/jwt/v4](https://togithub.com/golang-jwt/jwt) | require | major | `v4.5.0` -> `v5.0.0` | --- ### ⚠ Dependency Lookup Warnings ⚠ Warnings were logged while processing this repo. Please check the Dependency Dashboard for more information. --- ### Release Notes <details> <summary>golang-jwt/jwt (github.com/golang-jwt/jwt/v4)</summary> ### [`v5.0.0`](https://togithub.com/golang-jwt/jwt/releases/tag/v5.0.0) [Compare Source](https://togithub.com/golang-jwt/jwt/compare/v4.5.0...v5.0.0) ### 🚀 New Major Version `v5` 🚀 It's finally here, the release you have been waiting for! We don't take breaking changes lightly, but the changes outlined below were necessary to address some of the challenges of the previous API. A big thanks for [@mfridman](https://togithub.com/mfridman) for all the reviews, all contributors for their commits and of course [@dgrijalva](https://togithub.com/dgrijalva) for the original code. I hope we kept some of the spirit of your original `v4` branch alive in the approach we have taken here. \~[@oxisto](https://togithub.com/oxisto), on behalf of [@golang-jwt/maintainers](https://togithub.com/golang-jwt/maintainers) Version `v5` contains a major rework of core functionalities in the `jwt-go` library. This includes support for several validation options as well as a re-design of the `Claims` interface. Lastly, we reworked how errors work under the hood, which should provide a better overall developer experience. Starting from [v5.0.0](https://togithub.com/golang-jwt/jwt/releases/tag/v5.0.0), the import path will be: "github.com/golang-jwt/jwt/v5" For most users, changing the import path *should* suffice. However, since we intentionally changed and cleaned some of the public API, existing programs might need to be updated. The following sections describe significant changes and corresponding updates for existing programs. #### Parsing and Validation Options Under the hood, a new `validator` struct takes care of validating the claims. A long awaited feature has been the option to fine-tune the validation of tokens. This is now possible with several `ParserOption` functions that can be appended to most `Parse` functions, such as `ParseWithClaims`. The most important options and changes are: - Added `WithLeeway` to support specifying the leeway that is allowed when validating time-based claims, such as `exp` or `nbf`. - Changed default behavior to not check the `iat` claim. Usage of this claim is OPTIONAL according to the JWT RFC. The claim itself is also purely informational according to the RFC, so a strict validation failure is not recommended. If you want to check for sensible values in these claims, please use the `WithIssuedAt` parser option. - Added `WithAudience`, `WithSubject` and `WithIssuer` to support checking for expected `aud`, `sub` and `iss`. - Added `WithStrictDecoding` and `WithPaddingAllowed` options to allow previously global settings to enable base64 strict encoding and the parsing of base64 strings with padding. The latter is strictly speaking against the standard, but unfortunately some of the major identity providers issue some of these incorrect tokens. Both options are disabled by default. #### Changes to the `Claims` interface ##### Complete Restructuring Previously, the claims interface was satisfied with an implementation of a `Valid() error` function. This had several issues: - The different claim types (struct claims, map claims, etc.) then contained similar (but not 100 % identical) code of how this validation was done. This lead to a lot of (almost) duplicate code and was hard to maintain - It was not really semantically close to what a "claim" (or a set of claims) really is; which is a list of defined key/value pairs with a certain semantic meaning. Since all the validation functionality is now extracted into the validator, all `VerifyXXX` and `Valid` functions have been removed from the `Claims` interface. Instead, the interface now represents a list of getters to retrieve values with a specific meaning. This allows us to completely decouple the validation logic with the underlying storage representation of the claim, which could be a struct, a map or even something stored in a database. ```go type Claims interface { GetExpirationTime() (*NumericDate, error) GetIssuedAt() (*NumericDate, error) GetNotBefore() (*NumericDate, error) GetIssuer() (string, error) GetSubject() (string, error) GetAudience() (ClaimStrings, error) } ``` ##### Supported Claim Types and Removal of `StandardClaims` The two standard claim types supported by this library, `MapClaims` and `RegisteredClaims` both implement the necessary functions of this interface. The old `StandardClaims` struct, which has already been deprecated in `v4` is now removed. Users using custom claims, in most cases, will not experience any changes in the behavior as long as they embedded `RegisteredClaims`. If they created a new claim type from scratch, they now need to implemented the proper getter functions. ##### Migrating Application Specific Logic of the old `Valid` Previously, users could override the `Valid` method in a custom claim, for example to extend the validation with application-specific claims. However, this was always very dangerous, since once could easily disable the standard validation and signature checking. In order to avoid that, while still supporting the use-case, a new `ClaimsValidator` interface has been introduced. This interface consists of the `Validate() error` function. If the validator sees, that a `Claims` struct implements this interface, the errors returned to the `Validate` function will be *appended* to the regular standard validation. It is not possible to disable the standard validation anymore (even only by accident). Usage examples can be found in [example_test.go](./example_test.go), to build claims structs like the following. ```go // MyCustomClaims includes all registered claims, plus Foo. type MyCustomClaims struct { Foo string `json:"foo"` jwt.RegisteredClaims } // Validate can be used to execute additional application-specific claims // validation. func (m MyCustomClaims) Validate() error { if m.Foo != "bar" { return errors.New("must be foobar") } return nil } ``` #### Changes to the `Token` and `Parser` struct The previously global functions `DecodeSegment` and `EncodeSegment` were moved to the `Parser` and `Token` struct respectively. This will allow us in the future to configure the behavior of these two based on options supplied on the parser or the token (creation). This also removes two previously global variables and moves them to parser options `WithStrictDecoding` and `WithPaddingAllowed`. In order to do that, we had to adjust the way signing methods work. Previously they were given a base64 encoded signature in `Verify` and were expected to return a base64 encoded version of the signature in `Sign`, both as a `string`. However, this made it necessary to have `DecodeSegment` and `EncodeSegment` global and was a less than perfect design because we were repeating encoding/decoding steps for all signing methods. Now, `Sign` and `Verify` operate on a decoded signature as a `[]byte`, which feels more natural for a cryptographic operation anyway. Lastly, `Parse` and `SignedString` take care of the final encoding/decoding part. In addition to that, we also changed the `Signature` field on `Token` from a `string` to `[]byte` and this is also now populated with the decoded form. This is also more consistent, because the other parts of the JWT, mainly `Header` and `Claims` were already stored in decoded form in `Token`. Only the signature was stored in base64 encoded form, which was redundant with the information in the `Raw` field, which contains the complete token as base64. ```go type Token struct { Raw string // Raw contains the raw token Method SigningMethod // Method is the signing method used or to be used Header map[string]interface{} // Header is the first segment of the token in decoded form Claims Claims // Claims is the second segment of the token in decoded form Signature []byte // Signature is the third segment of the token in decoded form Valid bool // Valid specifies if the token is valid } ``` Most (if not all) of these changes should not impact the normal usage of this library. Only users directly accessing the `Signature` field as well as developers of custom signing methods should be affected. #### What's Changed - Added GitHub Actions Markdown by [@oxisto](https://togithub.com/oxisto) in [golang-jwt/jwt#260 - Remove `StandardClaims` in favor of `RegisteredClaims` by [@oxisto](https://togithub.com/oxisto) in [#235](https://togithub.com/golang-jwt/jwt/issues/235) - Adding more coverage by [@oxisto](https://togithub.com/oxisto) in [#268](https://togithub.com/golang-jwt/jwt/issues/268) - More consistent way of handling validation errors by [@oxisto](https://togithub.com/oxisto) in [#274](https://togithub.com/golang-jwt/jwt/issues/274) - New Validation API by [@oxisto](https://togithub.com/oxisto) in [golang-jwt/jwt#236 - `v5` Pre-Release by [@oxisto](https://togithub.com/oxisto) in [golang-jwt/jwt#234 - no need for string slice and call to strings.join by [@moneszarrugh](https://togithub.com/moneszarrugh) in [golang-jwt/jwt#115 - Update MIGRATION_GUIDE.md by [@liam-verta](https://togithub.com/liam-verta) in [golang-jwt/jwt#289 - Moving `DecodeSegement` to `Parser` by [@oxisto](https://togithub.com/oxisto) in [golang-jwt/jwt#278 - Adjusting the error checking example by [@oxisto](https://togithub.com/oxisto) in [golang-jwt/jwt#270 - add documentation to hmac `Verify` & `Sign` to detail why string is not an advisable input for key by [@dillonstreator](https://togithub.com/dillonstreator) in [golang-jwt/jwt#249 - Add golangci-lint by [@mfridman](https://togithub.com/mfridman) in [golang-jwt/jwt#279 - Added dependabot updates for GitHub actions by [@oxisto](https://togithub.com/oxisto) in [golang-jwt/jwt#298 - Bump actions/checkout from 2 to 3 by [@dependabot](https://togithub.com/dependabot) in [golang-jwt/jwt#299 - Bump actions/setup-go from 3 to 4 by [@dependabot](https://togithub.com/dependabot) in [golang-jwt/jwt#300 - Added coverage reporting by [@oxisto](https://togithub.com/oxisto) in [golang-jwt/jwt#304 - Last Documentation cleanups for `v5` release by [@oxisto](https://togithub.com/oxisto) in [golang-jwt/jwt#291 - enable jwt.ParsePublicKeyFromPEM to parse PKCS1 Public Key by [@twocs](https://togithub.com/twocs) in [golang-jwt/jwt#120 #### New Contributors - [@moneszarrugh](https://togithub.com/moneszarrugh) made their first contribution in [golang-jwt/jwt#115 - [@liam-verta](https://togithub.com/liam-verta) made their first contribution in [golang-jwt/jwt#289 - [@dillonstreator](https://togithub.com/dillonstreator) made their first contribution in [golang-jwt/jwt#249 - [@dependabot](https://togithub.com/dependabot) made their first contribution in [golang-jwt/jwt#299 - [@twocs](https://togithub.com/twocs) made their first contribution in [golang-jwt/jwt#120 **Full Changelog**: golang-jwt/jwt@v4.5.0...v5.0.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/woodpecker-ci/woodpecker).  --------- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: qwerty287 <ndev@web.de>

oxisto added the next The next iteration of development, currently `v6` label Aug 27, 2022

MicahParks mentioned this pull request Aug 28, 2022

Support for jwt v5 MicahParks/keyfunc#46

Merged

oxisto mentioned this pull request Dec 4, 2022

New validation API #236

Merged

5 tasks

oxisto and others added 3 commits December 9, 2022 18:04

oxisto force-pushed the v5 branch from 3d20909 to 1ef0fe8 Compare December 9, 2022 17:47

oxisto changed the title ~~Starting v5 development~~ v5 Release Dec 9, 2022

mfridman self-requested a review February 7, 2023 03:13

mfridman reviewed Feb 7, 2023

View reviewed changes

go.mod Show resolved Hide resolved

Cleanup and documentation of verification functions (#262)

3a9ee81

This PR adds further documentation to the validator and does an additional cleanup to make the VerifyXXX functions more managable.

mfridman reviewed Feb 19, 2023

View reviewed changes

oxisto and others added 4 commits February 19, 2023 16:22

Unexported some functions and types

66e2e01

Inlining application-specific validation

1e16f55

Update claims.go

8144967

Co-authored-by: Michael Fridman <mf192@icloud.com>

Adding more coverage (#268)

fa7a12b

github-actions bot reviewed Feb 20, 2023

View reviewed changes

map_claims_test.go Outdated Show resolved Hide resolved

oxisto added 2 commits February 20, 2023 23:05

Fixed test after unexporting parseString

57662e5

More documentation cleanup

4e6e1ba

oxisto mentioned this pull request Feb 20, 2023

Make issued at (iat) claim validation optional #175

Closed

oxisto added 2 commits February 21, 2023 08:54

More consistent way of handling validation errors (#274)

28dc523

Added initial migration guide

5dc3299

mfridman approved these changes Feb 21, 2023

View reviewed changes

mfridman reviewed Feb 21, 2023

View reviewed changes

MIGRATION_GUIDE.md

@@ -1,4 +1,82 @@

## Migration Guide (v4.0.0)

# Migration Guide (v5.0.0)

Copy link

Member

mfridman Feb 21, 2023 •

edited

Choose a reason for hiding this comment

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

Nicely documented.

oxisto changed the title ~~v5 Release~~ v5 Pre-Release Feb 21, 2023

oxisto merged commit 148d710 into main Feb 21, 2023

oxisto deleted the v5 branch February 21, 2023 13:32

oxisto restored the v5 branch February 21, 2023 13:37

oxisto added a commit to moneszarrugh/jwt that referenced this pull request Feb 21, 2023

v5 Pre-Release (golang-jwt#234)

19fc996

Co-authored-by: Micah Parks <66095735+MicahParks@users.noreply.github.com> Co-authored-by: Michael Fridman <mf192@icloud.com>

oxisto added a commit to twocs/jwt that referenced this pull request Mar 29, 2023

v5 Pre-Release (golang-jwt#234)

a02d89c

Co-authored-by: Micah Parks <66095735+MicahParks@users.noreply.github.com> Co-authored-by: Michael Fridman <mf192@icloud.com>

oxisto mentioned this pull request Sep 27, 2023

Restore .Valid() Functionality Somehow #348

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`v5` Pre-Release #234

`v5` Pre-Release #234

oxisto commented Aug 27, 2022 •

edited

mfridman commented Jan 7, 2023

oxisto commented Jan 8, 2023

oxisto commented Feb 21, 2023

mfridman commented Feb 21, 2023 •

edited

mfridman Feb 21, 2023 •

edited

		@@ -1,4 +1,82 @@
		## Migration Guide (v4.0.0)
		# Migration Guide (v5.0.0)

v5 Pre-Release #234

v5 Pre-Release #234

Conversation

oxisto commented Aug 27, 2022 • edited

mfridman commented Jan 7, 2023

oxisto commented Jan 8, 2023

oxisto commented Feb 21, 2023

mfridman commented Feb 21, 2023 • edited

mfridman Feb 21, 2023 • edited

Choose a reason for hiding this comment

`v5` Pre-Release #234

`v5` Pre-Release #234

oxisto commented Aug 27, 2022 •

edited

mfridman commented Feb 21, 2023 •

edited

mfridman Feb 21, 2023 •

edited