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

v4.4.1

What's Changed

• Add go1.18 to ci pipeline by @mfridman in #173
• Revert "feat: port clockskew support (#139)" by @mfridman in #184

Note, this release contains a Go module retraction for a prior release v4.4.0:

retract (
    v4.4.0 // Contains a backwards incompatible change to the Claims interface.
)

Full Changelog: v4.4.0...v4.4.1

v4.4.0

What's Changed

• fix: expired token error message by @ydylla in #165
• feat: port clockskew support by @ksegun in #139

New Contributors

• @ydylla made their first contribution in #165
• @ksegun made their first contribution in #139

Full Changelog: v4.3.0...v4.4.0

v4.3.0

What's Changed

• Support errors.Is for token extractors by @stefantds in #141
• Implementing Is(err) bool to support Go 1.13 style error checking by @oxisto in #136
• remove unnecessary for loop in token signing string for readability by @hyeonjae in #34
• updated README.md to contain more extensions by @matelang in #155
• Add JWT logo attribution by @mfridman in #161
• fix: fixed typo detect by cSpell by @giautm in #164
• Set json encoding precision by @mfridman in #162

New Contributors

• @stefantds made their first contribution in #141
• @hyeonjae made their first contribution in #34
• @matelang made their first contribution in #155
• @giautm made their first contribution in #164

Full Changelog: v4.2.0...v4.3.0

v4.2.0

• Fix the comment of VerifyExpiresAt (#109) @shogo82148
• Introducing functional-style options for the Parser type (#108) @oxisto
• Improve code comments, including security consideration (#107) @sebastien-rosset
• Fix int64 overflow in newNumericDateFromSeconds (#112) @PiotrKozimor
• Fixes jwt command to support EdDSA algorithm (#118) @AlexanderYastrebov
• Revert Encoding/Decoding changes for better compatibility (#117) @ajermaky
• Allow none algorithm in jwt command (#121) @AlexanderYastrebov
• Unwrap for ValidationError (#125) @kdeberk
• cmd: list supported algorithms (-alg flag) (#123) @AlexanderYastrebov
• Added VerifyIssuer method to RegisteredClaims (#130) @tfonfara

v4.1.0

• Adds support for go1.17 (#89).
• Adds RFC7519-compliant RegisteredClaims struct (#15). Use this instead of StandardClaims (deprecated but not removed).
• Adds generic crypto.Signer for ed25519.PublicKey (#95).
• Adds regular code scanning (#101).
• Corrects "exp" logic to conform to https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4 (#86).
• Adds additional parsing tests (#106).
• Changed error string (#97).
• Various Code fixes and cleanup (#53, #83, #102, #103).

v4.0.0

• Adds Go module support (#41). You can import this package using the following import path:

github.com/golang-jwt/jwt/v4

This release, and any future /v4 work is intended to be backwards-compatible with existing v3.x.y tags.

See the migration guide for more details.