Welcome to jwt-go, a go (or 'golang' for search engine friendliness) implementation of JSON Web Tokens.
Our support of Go versions is aligned with Go's version release policy. So we will support a major version of Go until there are two newer major releases. We no longer support building jwt-go with unsupported Go versions, as these contain security vulnerabilities which will not be fixed.
"},{"location":"#what-the-heck-is-a-jwt","title":"What the heck is a JWT?","text":"JWT.io has a great introduction to JSON Web Tokens.
In short, it's a signed JSON object that does something useful (for example, authentication). It's commonly used for Bearer tokens in OAuth 2.0 A token is made of three parts, separated by .'s. The first two parts are JSON objects, that have been base64url encoded. The last part is the signature, encoded the same way.
The first part is called the header. It contains the necessary information for verifying the last part, the signature. For example, which encryption method was used for signing and what key was used.
The part in the middle is the interesting bit. It's called the Claims and contains the actual stuff you care about. Refer to RFC 7519 for information about reserved keys and the proper way to add your own.
"},{"location":"#whats-in-the-box","title":"What's in the box?","text":"This library supports the parsing and verification as well as the generation and signing of JWTs. Current supported signing algorithms are HMAC SHA, RSA, RSA-PSS, ECDSA and EdDSA, though hooks are present for adding your own.
"},{"location":"#installation-guidelines","title":"Installation Guidelines","text":"To install the jwt package, you first need to have Go installed, then you can use the command below to add jwt-go as a dependency in your Go program.
go get -u github.com/golang-jwt/jwt/v5\nThen import it in your code:
import \"github.com/golang-jwt/jwt/v5\"\nOne of the primary goals of this library is to create a new JWT (or in short token).
"},{"location":"usage/create/#with-default-options","title":"With Default Options","text":"The easiest way to create a token is to use the jwt.New function. It then needs one of the available signing methods, to finally sign and convert the token into a string format (using the SignedString method). In the first example, we are using a symmetric signing method, i.e., HS256. For a symmetric method, both the signing and the verifying key are the same and thus, both must be equally protected (and should definitely NOT be stored in your code).
var (\nkey []byte\nt *jwt.Token\ns string\n)\nkey = /* Load key from somewhere, for example an environment variable */\nt = jwt.New(jwt.SigningMethodHS256) // (1)!\ns = t.SignedString(key) // (2)!\njwt.Token struct based on the supplied signing method. In this case a symmetric method is chosen.Signing using an asymmetric signing method (for example ECDSA) works quite similar. For an asymmetric method, the private key (which must be kept secret) is used to sign and the corresponding public key (which can be freely transmitted) is used to verify the token.
var (\nkey *ecdsa.PrivateKey\nt *jwt.Token\ns string\n)\nkey = /* Load key from somewhere, for example a file */\nt = jwt.New(jwt.SigningMethodES256) // (1)!\ns = t.SignedString(key) // (2)!\njwt.Token struct based on the supplied signing method. In this case a asymmetric method is chosen.Note, that the chosen signing method and the type of key must match. Please refer to Signing Methods for a complete overview.
"},{"location":"usage/create/#with-additional-claims","title":"With Additional Claims","text":"While the step above using jwt.New creates a valid token, it contains an empty set of claims. Claims are certain pieces of information that are encoded into the token. Since they are encoded and signed by the issuer of the token, one can assume that this information is valid (in the scope of the issuer). Claims can be used to provide the basis for user authentication or authorization, e.g., by encoding a user name or ID or roles into the token. This is also commonly in combination with OAuth 2.0. Furthermore, claims can also contain certain metadata about the token itself, e.g., the time until which the token is regarded as valid and not expired.
RFC 7519 provides a list of so called registered claim names 1, which each JWT parser needs to understand. Using the jwt.NewWithClaims, a token with different claims can be created.
var (\nkey *ecdsa.PrivateKey\nt *jwt.Token\ns string\n)\nkey = /* Load key from somewhere, for example a file */\nt = jwt.NewWithClaims(jwt.SigningMethodES256, // (1)!\njwt.MapClaims{ // (2)!\n\"iss\": \"my-auth-server\", // (3)!\n\"sub\": \"john\", // (4)!\n\"foo\": 2, // (5)!\n})\ns = t.SignedString(key) // (6)!\njwt.Token struct based on the supplied signing method. In this case a asymmetric method is chosen, which is the first parameter.jwt.Claims interface. In this case jwt.MapClaims are used, which is a wrapper type around a Go map containing string keys.\"sub\"3 claim is a registered claim name that contains the subject this token identifies, e.g. a user name. More technical, this claim identifies the principal that is the subject of the token.\"iss\"2 claim is a registered claim name that contains the issuer of the token. More technical, this claim identifies the principal that issued the token.\"foo\" claim is a custom claim containing a numeric value. Any string value can be chosen as a claim name, as long as it does not interfere with a registered claim name.While we already prepared a jwt.TokenOption type, which can be supplied as a varargs to jwt.New and jwt.NewWithClaims, these are strictly for future compatibility and are currently not used.
Section 4.1 of RFC 7519 \u21a9
Section 4.1.1 of RFC 7519 \u21a9
Section 4.1.2 of RFC 7519 \u21a9
WithValidMethods methods as []string Supplies a list of signing methods that the parser will check against the algorithm on the token. Only the supplied methods will be considered valid. It is heavily encouraged to use this option in order to prevent \"none\" algorithm attacks.1 WithJSONNumber - Configures the underlying JSON parser to use the UseNumber function, which decodes numeric JSON values into the json.Number type instead of float64. This type can then be used to convert the value into either a floating type or integer type. WithIssuer issuer as string Configures the validator to require the specified issuer in the \"iss\"2 claim. Validation will fail if a different issuer is specified in the token or the \"iss\" claim is missing. WithSubject subject as string Configures the validator to require the specified subject in the \"sub\"3 claim. Validation will fail if a different subject is specified in the token or the \"sub\" claim is missing. WithAudience audience as string Configures the validator to require the specified audience in the \"aud\"4 claim. Validation will fail if the audience is not listed in the token or the \"aud\" claim is missing. The contents of the audience string is application specific, but often contains the URI of the service that consumes the token. WithLeeway leeway as time.Duration According to the RFC, a certain time window (leeway) is allowed when verifying time based claims, such as expiration time. This is due to the fact that a there is not perfect clock synchronization on the a distributed system such as the internet. While we do not enforce any restriction on the amount of leeway, it should generally not exceed more than a few minutes.5 WithIssuedAt - Enables a sanity check of the \"iat\"6 claim. More specifically, when turning this option on, the validator will check if the issued-at time is not in the future. Danger Zone https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries \u21a9
Section 4.1.1 of RFC 7519 \u21a9
Section 4.1.2 of RFC 7519 \u21a9
Section 4.1.3 of RFC 7519 \u21a9
Section 4.1.4 of RFC 7519 \u21a9
Section 4.1.6 of RFC 7519 \u21a9
Note, that the chosen signing method and the type of key must match. Please refer to Signing Methods for a complete overview.
While the step above using jwt.New creates a valid token, it contains an empty set of claims. Claims are certain pieces of information that are encoded into the token. Since they are encoded and signed by the issuer of the token, one can assume that this information is valid (in the scope of the issuer). Claims can be used to provide the basis for user authentication or authorization, e.g., by encoding a user name or ID or roles into the token. This is also commonly in combination with OAuth 2.0. Furthermore, claims can also contain certain metadata about the token itself, e.g., the time until which the token is regarded as valid and not expired.
RFC 7519 provides a list of so called registered claim names 1, which each JWT parser needs to understand. Using the jwt.NewWithClaims, a token with different claims can be created.
var (
+ key *ecdsa.PrivateKey
+ t *jwt.Token
+ s string
+)
+
+key = /* Load key from somewhere, for example a file */
+t = jwt.NewWithClaims(jwt.SigningMethodES256, // (1)!
+ jwt.MapClaims{ // (2)!
+ "iss": "my-auth-server", // (3)!
+ "sub": "john", // (4)!
+ "foo": 2, // (5)!
+ })
+s = t.SignedString(key) // (6)!
+jwt.Token struct based on the supplied signing method. In this case a asymmetric method is chosen, which is the first parameter.jwt.Claims interface. In this case jwt.MapClaims are used, which is a wrapper type around a Go map containing string keys."sub"3 claim is a registered claim name that contains the subject this token identifies, e.g. a user name. More technical, this claim identifies the principal that is the subject of the token."iss"2 claim is a registered claim name that contains the issuer of the token. More technical, this claim identifies the principal that issued the token."foo" claim is a custom claim containing a numeric value. Any string value can be chosen as a claim name, as long as it does not interfere with a registered claim name.While we already prepared a
jwt.TokenOption
@@ -460,6 +519,20 @@ type, which can be supplied as a varargs to
jwt.New and
jwt.NewWithClaims,
these are strictly for future compatibility and are currently not used.
https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries ↩
https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1 ↩
+https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2 ↩
+https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3 ↩
+https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4 ↩
+https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6 ↩
+