v4.5.1

Security

Unclear documentation of the error behavior in ParseWithClaims in <= 4.5.0 could lead to situation where users are potentially not checking errors in the way they should be. Especially, if a token is both expired and invalid, the errors returned by ParseWithClaims return both error codes. If users only check for the jwt.ErrTokenExpired using error.Is, they will ignore the embedded jwt.ErrTokenSignatureInvalid and thus potentially accept invalid tokens.

This issue was documented in GHSA-29wx-vh33-7x7r and fixed in this release.

Note: v5 was not affected by this issue. So upgrading to this release version is also recommended.

What's Changed

• Back-ported error-handling logic in ParseWithClaims from v5 branch. This fixes GHSA-29wx-vh33-7x7r.

Full Changelog: v4.5.0...v4.5.1

v5.2.1

What's Changed

• chore: remove unnecessary conversions from tests by @estensen in #370
• Trivial: Typo fix for ECDSA error message by @tjs-cinemo in #373
• Fix incorrect error return by @ss49919201 in #371

New Contributors

• @tjs-cinemo made their first contribution in #373
• @ss49919201 made their first contribution in #371

Full Changelog: v5.2.0...v5.2.1

v5.2.0

What's Changed

• Exported NewValidator by @oxisto in #349
• Improve ErrInvalidKeyType error messages by @Laurin-Notemann in #361
• Update MIGRATION_GUIDE.md by @jbarham in #363

New Contributors

• @Laurin-Notemann made their first contribution in #361
• @jbarham made their first contribution in #363

Full Changelog: v5.1.0...v5.2.0

v5.1.0

What's Changed

• Using jwt's native ErrInvalidType instead of json.UnsupportedTypeError by @oxisto in #316
• Fix typos in comments and test names by @alexandear in #317
• Format: add whitespaces, remove empty lines by @alexandear in #319
• Refactor example: use io.ReadAll instead of io.Copy by @alexandear in #320
• Refactor code by using switch instead of if-else by @alexandear in #318
• A quick way to validate token string by @dcalsky in #302
• Refactor: remove unnecessary []byte conversion to string by @alexandear in #330
• Refactor: compare strings with strings.EqualFold by @alexandear in #329
• Avoid use of json.NewDecoder by @craigpastro in #313
• Update ParseUnverified godoc by @duhaesbaert in #341
• Update ci workflows (add go1.21) by @mfridman in #345
• Bump actions/checkout from 3 to 4 by @dependabot in #346
• Key rotation with VerificationKeySet by @mfridman in #344
• Add explicit ClaimsValidator implementation check for custom claims by @epelc in #343
• feat: allow making exp claim required by @tareksha in #351
• Add error handling to examples by @craigpastro in #312

New Contributors

• @alexandear made their first contribution in #317
• @dcalsky made their first contribution in #302
• @craigpastro made their first contribution in #313
• @duhaesbaert made their first contribution in #341
• @epelc made their first contribution in #343
• @tareksha made their first contribution in #351

Full Changelog: v5.0.0...v5.1.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 for all the reviews, all contributors for their commits and of course @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, on behalf of @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, 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.

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, to build claims structs like the following.

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

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 in #260
• Remove StandardClaims in favor of RegisteredClaims by @oxisto in #235
• Adding more coverage by @oxisto in #268
• More consistent way of handling validation errors by @oxisto in #274
• New Validation API by @oxisto in #236
• v5 Pre-Release by @oxisto in #234
• no need for string slice and call to strings.join by @moneszarrugh in #115
• Update MIGRATION_GUIDE.md by @liam-verta in #289
• Moving DecodeSegement to Parser by @oxisto in #278
• Adjusting the error checking example by @oxisto in #270
• add documentation to hmac Verify & Sign to detail why string is not an advisable input for key by @dillonstreator in #249
• Add golangci-lint by @mfridman in #279
• Added dependabot updates for GitHub actions by @oxisto in #298
• Bump actions/checkout from 2 to 3 by @dependabot in #299
• Bump actions/setup-go from 3 to 4 by @dependabot in #300
• Added coverage reporting by @oxisto in #304
• Last Documentation cleanups for v5 release by @oxisto in #291
• enable jwt.ParsePublicKeyFromPEM to parse PKCS1 Public Key by @twocs in #120

New Contributors

• @moneszarrugh made their first contribution in #115
• @liam-verta made their first contribution in #289
• @dillonstreator made their first contribution in https://github.c...

v5.0.0-rc.2

What's Changed

• Added GitHub Actions Markdown by @oxisto in #260
• v5 Pre-Release by @oxisto in #234
• no need for string slice and call to strings.join by @moneszarrugh in #115
• Update MIGRATION_GUIDE.md by @liam-verta in #289
• Moving DecodeSegement to Parser by @oxisto in #278
• Adjusting the error checking example by @oxisto in #270

New Contributors

• @moneszarrugh made their first contribution in #115
• @liam-verta made their first contribution in #289

Full Changelog: v4.5.0...v5.0.0-rc.2

v5.0.0-rc.1

🚨 New major version v5 (release candidate 1) 🚨

Huge kudos to @oxisto for pushing this 10+ year-old project further and building a solid foundation. We don't take breaking changes lightly, but the changes outlined below were necessary to address some of the shortcomings of the previous API.

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, 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 adopted. The following paragraphs go through the individual changes and make suggestions how to change existing programs.

The existing v4 version is available on the v4 branch at commit 9358574

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:

• WithLeeway, which can be used to specific leeway that is taken into account when validating time-based claims, such as exp or nbf.
• The new default behavior now disables checking the iat claim by default. 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.
• New options have also been added to check for expected aud, sub and iss, namely WithAudience, WithSubject and WithIssuer.

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.

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, to build claims structs like the following.

// 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
}

v4.5.0

What's Changed

• Allow strict base64 decoding by @AlexanderYastrebov in #259

Full Changelog: v4.4.3...v4.5.0

v4.4.3

What's Changed

• fix: link update for README.md for v4 by @krokite in #217
• Implement a BearerExtractor by @WhyNotHugo in #226
• Bump matrix to support latest go version (go1.19) by @mfridman in #231
• Include https://github.com/golang-jwt/jwe in README by @oxisto in #229
• Add doc comment to ParseWithClaims by @jkopczyn in #232
• Refactor: removed the unneeded if statement by @Krout0n in #241
• No pointer embedding in the example by @oxisto in #255

New Contributors

• @krokite made their first contribution in #217
• @WhyNotHugo made their first contribution in #226
• @jkopczyn made their first contribution in #232
• @Krout0n made their first contribution in #241

Full Changelog: v4.4.2...v4.4.3

v4.4.2

What's Changed

• Added MicahParks/keyfunc to extensions by @oxisto in #194
• Update link to v4 on pkg.go.dev page by @polRk in #195
• add installation guidelines to the README file by @morelmiles in #204
• chore: replace ioutil with io and os by @estensen in #198
• CI check for Go code formatting by @mfridman in #206
• Create SECURITY.md by @mfridman in #171
• Update SECURITY.md by @oxisto in #207
• Fixed integer overflow in NumericDate.MarshalJSON by @qqiao in #200
• Claims in rsa_test.go Table Driven Test are Unused by @gkech in #212

New Contributors

• @polRk made their first contribution in #195
• @morelmiles made their first contribution in #204
• @estensen made their first contribution in #198
• @qqiao made their first contribution in #200
• @gkech made their first contribution in #212

Full Changelog: v4.4.1...v4.4.2