You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Version `v5` contains a major rework of core functionalities in the `jwt-go` library. This includes support for several
4
+
validation options as well as a re-design of the `Claims` interface. Lastly, we reworked how errors work under the hood,
5
+
which should provide a better overall developer experience.
6
+
7
+
Starting from [v5.0.0](https://github.com/golang-jwt/jwt/releases/tag/v5.0.0), the import path will be:
8
+
9
+
"github.com/golang-jwt/jwt/v5"
10
+
11
+
For most users, changing the import path *should* suffice. However, since we intentionally changed and cleaned some of
12
+
the public API, existing programs might need to be adopted. The following paragraphs go through the individual changes
13
+
and make suggestions how to change existing programs.
14
+
15
+
## Parsing and Validation Options
16
+
17
+
Under the hood, a new `validator` struct takes care of validating the claims. A long awaited feature has been the option
18
+
to fine-tune the validation of tokens. This is now possible with several `ParserOption` functions that can be appended
19
+
to most `Parse` functions, such as `ParseWithClaims`. The most important options and changes are:
20
+
*`WithLeeway`, which can be used to specific leeway that is taken into account when validating time-based claims, such as `exp` or `nbf`.
21
+
* 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.
22
+
* New options have also been added to check for expected `aud`, `sub` and `iss`, namely `WithAudience`, `WithSubject` and `WithIssuer`.
23
+
24
+
## Changes to the `Claims` interface
25
+
26
+
### Complete Restructuring
27
+
28
+
Previously, the claims interface was satisfied with an implementation of a `Valid() error` function. This had several issues:
29
+
* 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
30
+
* 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.
31
+
32
+
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.
33
+
34
+
```go
35
+
typeClaimsinterface {
36
+
GetExpirationTime() (*NumericDate, error)
37
+
GetIssuedAt() (*NumericDate, error)
38
+
GetNotBefore() (*NumericDate, error)
39
+
GetIssuer() (string, error)
40
+
GetSubject() (string, error)
41
+
GetAudience() (ClaimStrings, error)
42
+
}
43
+
```
44
+
45
+
### Supported Claim Types and Removal of `StandardClaims`
46
+
47
+
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.
48
+
49
+
Users using custom claims, in most cases, will not experience any changes in the behavior as long as they embedded
50
+
`RegisteredClaims`. If they created a new claim type from scratch, they now need to implemented the proper getter
51
+
functions.
52
+
53
+
### Migrating Application Specific Logic of the old `Valid`
54
+
55
+
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.
56
+
57
+
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).
58
+
59
+
Usage examples can be found in [example_test.go](./example_test.go), to build claims structs like the following.
60
+
61
+
```go
62
+
// MyCustomClaims includes all registered claims, plus Foo.
63
+
typeMyCustomClaimsstruct {
64
+
Foostring`json:"foo"`
65
+
jwt.RegisteredClaims
66
+
}
67
+
68
+
// Validate can be used to execute additional application-specific claims
69
+
// validation.
70
+
func(mMyCustomClaims) Validate() error {
71
+
if m.Foo != "bar" {
72
+
return errors.New("must be foobar")
73
+
}
74
+
75
+
returnnil
76
+
}
77
+
```
78
+
79
+
# Migration Guide (v4.0.0)
2
80
3
81
Starting from [v4.0.0](https://github.com/golang-jwt/jwt/releases/tag/v4.0.0), the import path will be:
4
82
@@ -8,7 +86,7 @@ The `/v4` version will be backwards compatible with existing `v3.x.y` tags in th
8
86
`github.com/dgrijalva/jwt-go`. For most users this should be a drop-in replacement, if you're having
9
87
troubles migrating, please open an issue.
10
88
11
-
You can replace all occurrences of `github.com/dgrijalva/jwt-go` or `github.com/golang-jwt/jwt` with `github.com/golang-jwt/jwt/v4`, either manually or by using tools such as `sed` or `gofmt`.
89
+
You can replace all occurrences of `github.com/dgrijalva/jwt-go` or `github.com/golang-jwt/jwt` with `github.com/golang-jwt/jwt/v5`, either manually or by using tools such as `sed` or `gofmt`.
12
90
13
91
And then you'd typically run:
14
92
@@ -17,6 +95,6 @@ go get github.com/golang-jwt/jwt/v4
17
95
go mod tidy
18
96
```
19
97
20
-
##Older releases (before v3.2.0)
98
+
# Older releases (before v3.2.0)
21
99
22
100
The original migration guide for older releases can be found at https://github.com/dgrijalva/jwt-go/blob/master/MIGRATION_GUIDE.md.
A [go](http://www.golang.org) (or 'golang' for search engine friendliness) implementation of [JSON Web Tokens](https://datatracker.ietf.org/doc/html/rfc7519).
7
7
8
8
Starting with [v4.0.0](https://github.com/golang-jwt/jwt/releases/tag/v4.0.0) this project adds Go module support, but maintains backwards compatibility with older `v3.x.y` tags and upstream `github.com/dgrijalva/jwt-go`.
9
-
See the [`MIGRATION_GUIDE.md`](./MIGRATION_GUIDE.md) for more information.
9
+
See the [`MIGRATION_GUIDE.md`](./MIGRATION_GUIDE.md) for more information. Version v5.0.0 introduces major improvements to the validation of tokens, but is not entirely backwards compatible.
10
10
11
11
> After the original author of the library suggested migrating the maintenance of `jwt-go`, a dedicated team of open source maintainers decided to clone the existing library into this repository. See [dgrijalva/jwt-go#462](https://github.com/dgrijalva/jwt-go/issues/462) for a detailed discussion on this topic.
12
12
@@ -41,22 +41,22 @@ This library supports the parsing and verification as well as the generation and
41
41
1. To install the jwt package, you first need to have [Go](https://go.dev/doc/install) installed, then you can use the command below to add `jwt-go` as a dependency in your Go program.
42
42
43
43
```sh
44
-
go get -u github.com/golang-jwt/jwt/v4
44
+
go get -u github.com/golang-jwt/jwt/v5
45
45
```
46
46
47
47
2. Import it in your code:
48
48
49
49
```go
50
-
import"github.com/golang-jwt/jwt/v4"
50
+
import"github.com/golang-jwt/jwt/v5"
51
51
```
52
52
53
53
## Examples
54
54
55
-
See [the project documentation](https://pkg.go.dev/github.com/golang-jwt/jwt/v4) for examples of usage:
55
+
See [the project documentation](https://pkg.go.dev/github.com/golang-jwt/jwt/v5) for examples of usage:
56
56
57
-
*[Simple example of parsing and validating a token](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#example-Parse-Hmac)
58
-
*[Simple example of building and signing a token](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#example-New-Hmac)
59
-
*[Directory of Examples](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#pkg-examples)
57
+
*[Simple example of parsing and validating a token](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#example-Parse-Hmac)
58
+
*[Simple example of building and signing a token](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#example-New-Hmac)
59
+
*[Directory of Examples](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#pkg-examples)
60
60
61
61
## Extensions
62
62
@@ -68,7 +68,7 @@ A common use case would be integrating with different 3rd party signature provid
| JWKS | Provides support for JWKS ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) as a `jwt.Keyfunc`|https://github.com/MicahParks/keyfunc|
71
+
| JWKS | Provides support for JWKS ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) as a `jwt.Keyfunc`|https://github.com/MicahParks/keyfunc|
72
72
73
73
*Disclaimer*: Unless otherwise specified, these integrations are maintained by third parties and should not be considered as a primary offer by any of the mentioned cloud providers
74
74
@@ -110,10 +110,10 @@ Asymmetric signing methods, such as RSA, use different keys for signing and veri
110
110
111
111
Each signing method expects a different object type for its signing keys. See the package documentation for details. Here are the most common ones:
112
112
113
-
* The [HMAC signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#SigningMethodHMAC) (`HS256`,`HS384`,`HS512`) expect `[]byte` values for signing and validation
114
-
* The [RSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#SigningMethodRSA) (`RS256`,`RS384`,`RS512`) expect `*rsa.PrivateKey` for signing and `*rsa.PublicKey` for validation
115
-
* The [ECDSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#SigningMethodECDSA) (`ES256`,`ES384`,`ES512`) expect `*ecdsa.PrivateKey` for signing and `*ecdsa.PublicKey` for validation
116
-
* The [EdDSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v4#SigningMethodEd25519) (`Ed25519`) expect `ed25519.PrivateKey` for signing and `ed25519.PublicKey` for validation
113
+
* The [HMAC signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodHMAC) (`HS256`,`HS384`,`HS512`) expect `[]byte` values for signing and validation
114
+
* The [RSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodRSA) (`RS256`,`RS384`,`RS512`) expect `*rsa.PrivateKey` for signing and `*rsa.PublicKey` for validation
115
+
* The [ECDSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodECDSA) (`ES256`,`ES384`,`ES512`) expect `*ecdsa.PrivateKey` for signing and `*ecdsa.PublicKey` for validation
116
+
* The [EdDSA signing method](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#SigningMethodEd25519) (`Ed25519`) expect `ed25519.PrivateKey` for signing and `ed25519.PublicKey` for validation
117
117
118
118
### JWT and OAuth
119
119
@@ -131,7 +131,7 @@ This library uses descriptive error messages whenever possible. If you are not g
131
131
132
132
## More
133
133
134
-
Documentation can be found [on pkg.go.dev](https://pkg.go.dev/github.com/golang-jwt/jwt/v4).
134
+
Documentation can be found [on pkg.go.dev](https://pkg.go.dev/github.com/golang-jwt/jwt/v5).
135
135
136
136
The command line utility included in this project (cmd/jwt) provides a straightforward example of token creation and parsing as well as a useful tool for debugging your own integration. You'll also find several implementation examples in the documentation.
Copy file name to clipboardExpand all lines: VERSION_HISTORY.md
+9-7Lines changed: 9 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,19 @@
1
-
##`jwt-go` Version History
1
+
# `jwt-go` Version History
2
2
3
-
#### 4.0.0
3
+
The following version history is kept for historic purposes. To retrieve the current changes of each version, please refer to the change-log of the specific release versions on https://github.com/golang-jwt/jwt/releases.
4
+
5
+
## 4.0.0
4
6
5
7
* Introduces support for Go modules. The `v4` version will be backwards compatible with `v3.x.y`.
6
8
7
-
####3.2.2
9
+
## 3.2.2
8
10
9
11
* Starting from this release, we are adopting the policy to support the most 2 recent versions of Go currently available. By the time of this release, this is Go 1.15 and 1.16 ([#28](https://github.com/golang-jwt/jwt/pull/28)).
10
12
* Fixed a potential issue that could occur when the verification of `exp`, `iat` or `nbf` was not required and contained invalid contents, i.e. non-numeric/date. Thanks for @thaJeztah for making us aware of that and @giorgos-f3 for originally reporting it to the formtech fork ([#40](https://github.com/golang-jwt/jwt/pull/40)).
11
13
* Added support for EdDSA / ED25519 ([#36](https://github.com/golang-jwt/jwt/pull/36)).
0 commit comments