diff options
Diffstat (limited to 'vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md')
-rw-r--r-- | vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md | 195 |
1 files changed, 0 insertions, 195 deletions
diff --git a/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md b/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md deleted file mode 100644 index ff9c57e..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md +++ /dev/null | |||
@@ -1,195 +0,0 @@ | |||
1 | # Migration Guide (v5.0.0) | ||
2 | |||
3 | Version `v5` contains a major rework of core functionalities in the `jwt-go` | ||
4 | library. This includes support for several validation options as well as a | ||
5 | re-design of the `Claims` interface. Lastly, we reworked how errors work under | ||
6 | the hood, which should provide a better overall developer experience. | ||
7 | |||
8 | Starting from [v5.0.0](https://github.com/golang-jwt/jwt/releases/tag/v5.0.0), | ||
9 | the import path will be: | ||
10 | |||
11 | "github.com/golang-jwt/jwt/v5" | ||
12 | |||
13 | For most users, changing the import path *should* suffice. However, since we | ||
14 | intentionally changed and cleaned some of the public API, existing programs | ||
15 | might need to be updated. The following sections describe significant changes | ||
16 | and corresponding updates for existing programs. | ||
17 | |||
18 | ## Parsing and Validation Options | ||
19 | |||
20 | Under the hood, a new `Validator` struct takes care of validating the claims. A | ||
21 | long awaited feature has been the option to fine-tune the validation of tokens. | ||
22 | This is now possible with several `ParserOption` functions that can be appended | ||
23 | to most `Parse` functions, such as `ParseWithClaims`. The most important options | ||
24 | and changes are: | ||
25 | * Added `WithLeeway` to support specifying the leeway that is allowed when | ||
26 | validating time-based claims, such as `exp` or `nbf`. | ||
27 | * Changed default behavior to not check the `iat` claim. Usage of this claim | ||
28 | is OPTIONAL according to the JWT RFC. The claim itself is also purely | ||
29 | informational according to the RFC, so a strict validation failure is not | ||
30 | recommended. If you want to check for sensible values in these claims, | ||
31 | please use the `WithIssuedAt` parser option. | ||
32 | * Added `WithAudience`, `WithSubject` and `WithIssuer` to support checking for | ||
33 | expected `aud`, `sub` and `iss`. | ||
34 | * Added `WithStrictDecoding` and `WithPaddingAllowed` options to allow | ||
35 | previously global settings to enable base64 strict encoding and the parsing | ||
36 | of base64 strings with padding. The latter is strictly speaking against the | ||
37 | standard, but unfortunately some of the major identity providers issue some | ||
38 | of these incorrect tokens. Both options are disabled by default. | ||
39 | |||
40 | ## Changes to the `Claims` interface | ||
41 | |||
42 | ### Complete Restructuring | ||
43 | |||
44 | Previously, the claims interface was satisfied with an implementation of a | ||
45 | `Valid() error` function. This had several issues: | ||
46 | * The different claim types (struct claims, map claims, etc.) then contained | ||
47 | similar (but not 100 % identical) code of how this validation was done. This | ||
48 | lead to a lot of (almost) duplicate code and was hard to maintain | ||
49 | * It was not really semantically close to what a "claim" (or a set of claims) | ||
50 | really is; which is a list of defined key/value pairs with a certain | ||
51 | semantic meaning. | ||
52 | |||
53 | Since all the validation functionality is now extracted into the validator, all | ||
54 | `VerifyXXX` and `Valid` functions have been removed from the `Claims` interface. | ||
55 | Instead, the interface now represents a list of getters to retrieve values with | ||
56 | a specific meaning. This allows us to completely decouple the validation logic | ||
57 | with the underlying storage representation of the claim, which could be a | ||
58 | struct, a map or even something stored in a database. | ||
59 | |||
60 | ```go | ||
61 | type Claims interface { | ||
62 | GetExpirationTime() (*NumericDate, error) | ||
63 | GetIssuedAt() (*NumericDate, error) | ||
64 | GetNotBefore() (*NumericDate, error) | ||
65 | GetIssuer() (string, error) | ||
66 | GetSubject() (string, error) | ||
67 | GetAudience() (ClaimStrings, error) | ||
68 | } | ||
69 | ``` | ||
70 | |||
71 | Users that previously directly called the `Valid` function on their claims, | ||
72 | e.g., to perform validation independently of parsing/verifying a token, can now | ||
73 | use the `jwt.NewValidator` function to create a `Validator` independently of the | ||
74 | `Parser`. | ||
75 | |||
76 | ```go | ||
77 | var v = jwt.NewValidator(jwt.WithLeeway(5*time.Second)) | ||
78 | v.Validate(myClaims) | ||
79 | ``` | ||
80 | |||
81 | ### Supported Claim Types and Removal of `StandardClaims` | ||
82 | |||
83 | The two standard claim types supported by this library, `MapClaims` and | ||
84 | `RegisteredClaims` both implement the necessary functions of this interface. The | ||
85 | old `StandardClaims` struct, which has already been deprecated in `v4` is now | ||
86 | removed. | ||
87 | |||
88 | Users using custom claims, in most cases, will not experience any changes in the | ||
89 | behavior as long as they embedded `RegisteredClaims`. If they created a new | ||
90 | claim type from scratch, they now need to implemented the proper getter | ||
91 | functions. | ||
92 | |||
93 | ### Migrating Application Specific Logic of the old `Valid` | ||
94 | |||
95 | Previously, users could override the `Valid` method in a custom claim, for | ||
96 | example to extend the validation with application-specific claims. However, this | ||
97 | was always very dangerous, since once could easily disable the standard | ||
98 | validation and signature checking. | ||
99 | |||
100 | In order to avoid that, while still supporting the use-case, a new | ||
101 | `ClaimsValidator` interface has been introduced. This interface consists of the | ||
102 | `Validate() error` function. If the validator sees, that a `Claims` struct | ||
103 | implements this interface, the errors returned to the `Validate` function will | ||
104 | be *appended* to the regular standard validation. It is not possible to disable | ||
105 | the standard validation anymore (even only by accident). | ||
106 | |||
107 | Usage examples can be found in [example_test.go](./example_test.go), to build | ||
108 | claims structs like the following. | ||
109 | |||
110 | ```go | ||
111 | // MyCustomClaims includes all registered claims, plus Foo. | ||
112 | type MyCustomClaims struct { | ||
113 | Foo string `json:"foo"` | ||
114 | jwt.RegisteredClaims | ||
115 | } | ||
116 | |||
117 | // Validate can be used to execute additional application-specific claims | ||
118 | // validation. | ||
119 | func (m MyCustomClaims) Validate() error { | ||
120 | if m.Foo != "bar" { | ||
121 | return errors.New("must be foobar") | ||
122 | } | ||
123 | |||
124 | return nil | ||
125 | } | ||
126 | ``` | ||
127 | |||
128 | ## Changes to the `Token` and `Parser` struct | ||
129 | |||
130 | The previously global functions `DecodeSegment` and `EncodeSegment` were moved | ||
131 | to the `Parser` and `Token` struct respectively. This will allow us in the | ||
132 | future to configure the behavior of these two based on options supplied on the | ||
133 | parser or the token (creation). This also removes two previously global | ||
134 | variables and moves them to parser options `WithStrictDecoding` and | ||
135 | `WithPaddingAllowed`. | ||
136 | |||
137 | In order to do that, we had to adjust the way signing methods work. Previously | ||
138 | they were given a base64 encoded signature in `Verify` and were expected to | ||
139 | return a base64 encoded version of the signature in `Sign`, both as a `string`. | ||
140 | However, this made it necessary to have `DecodeSegment` and `EncodeSegment` | ||
141 | global and was a less than perfect design because we were repeating | ||
142 | encoding/decoding steps for all signing methods. Now, `Sign` and `Verify` | ||
143 | operate on a decoded signature as a `[]byte`, which feels more natural for a | ||
144 | cryptographic operation anyway. Lastly, `Parse` and `SignedString` take care of | ||
145 | the final encoding/decoding part. | ||
146 | |||
147 | In addition to that, we also changed the `Signature` field on `Token` from a | ||
148 | `string` to `[]byte` and this is also now populated with the decoded form. This | ||
149 | is also more consistent, because the other parts of the JWT, mainly `Header` and | ||
150 | `Claims` were already stored in decoded form in `Token`. Only the signature was | ||
151 | stored in base64 encoded form, which was redundant with the information in the | ||
152 | `Raw` field, which contains the complete token as base64. | ||
153 | |||
154 | ```go | ||
155 | type Token struct { | ||
156 | Raw string // Raw contains the raw token | ||
157 | Method SigningMethod // Method is the signing method used or to be used | ||
158 | Header map[string]interface{} // Header is the first segment of the token in decoded form | ||
159 | Claims Claims // Claims is the second segment of the token in decoded form | ||
160 | Signature []byte // Signature is the third segment of the token in decoded form | ||
161 | Valid bool // Valid specifies if the token is valid | ||
162 | } | ||
163 | ``` | ||
164 | |||
165 | Most (if not all) of these changes should not impact the normal usage of this | ||
166 | library. Only users directly accessing the `Signature` field as well as | ||
167 | developers of custom signing methods should be affected. | ||
168 | |||
169 | # Migration Guide (v4.0.0) | ||
170 | |||
171 | Starting from [v4.0.0](https://github.com/golang-jwt/jwt/releases/tag/v4.0.0), | ||
172 | the import path will be: | ||
173 | |||
174 | "github.com/golang-jwt/jwt/v4" | ||
175 | |||
176 | The `/v4` version will be backwards compatible with existing `v3.x.y` tags in | ||
177 | this repo, as well as `github.com/dgrijalva/jwt-go`. For most users this should | ||
178 | be a drop-in replacement, if you're having troubles migrating, please open an | ||
179 | issue. | ||
180 | |||
181 | You can replace all occurrences of `github.com/dgrijalva/jwt-go` or | ||
182 | `github.com/golang-jwt/jwt` with `github.com/golang-jwt/jwt/v4`, either manually | ||
183 | or by using tools such as `sed` or `gofmt`. | ||
184 | |||
185 | And then you'd typically run: | ||
186 | |||
187 | ``` | ||
188 | go get github.com/golang-jwt/jwt/v4 | ||
189 | go mod tidy | ||
190 | ``` | ||
191 | |||
192 | # Older releases (before v3.2.0) | ||
193 | |||
194 | The original migration guide for older releases can be found at | ||
195 | https://github.com/dgrijalva/jwt-go/blob/master/MIGRATION_GUIDE.md. | ||