golang-jwt/jwt

The jwt tool allows you to sign, verify, and inspect JSON Web Tokens from the command line.

Important Requirements:

• Key files must be in PEM format. Other formats are not supported.

Common Tasks:

• Sign and Verify a token in one pipeline: You can pipe a JSON payload into the tool to sign it, then pipe the resulting token into the tool again to verify it and output the original claims.

• Display a token's contents: To simply inspect a token without signing or verifying, use the -show flag.

Starting from v4.0.0, the import path is github.com/golang-jwt/jwt/v4. This version is backwards compatible with v3.x.y and github.com/dgrijalva/jwt-go.

To migrate:

1. Replace all occurrences of github.com/dgrijalva/jwt-go or github.com/golang-jwt/jwt with github.com/golang-jwt/jwt/v4.
2. Run the following commands:

go get github.com/golang-jwt/jwt/v4
go mod tidy

Starting from v5.0.0, the import path has changed. Update your import statements to use the new path:

"github.com/golang-jwt/jwt/v5"

Note that v5 includes a major rework of core functionalities, including a redesigned Claims interface and new validation options. While changing the import path is the first step, you may need to update your code to accommodate changes in the public API.

Starting from version 3.2.1, the import path for the library has changed. You must update your import statements from the old path to the new one to ensure compatibility and security fixes.

Old path: github.com/dgrijalva/jwt-go New path: github.com/golang-jwt/jwt

The project provides several examples for common tasks, including:

• Parsing and validating a token (e.g., HMAC)
• Building and signing a token (e.g., HMAC)

Detailed examples can be found in the official package documentation.

In version 2.0.0, the KeyFunc signature was changed to support a wider variety of signing methods beyond just []byte. When using Parse, you must update your KeyFunc to return interface{} instead of []byte.

Required change: Change func(t *jwt.Token) ([]byte, error) to func(t *jwt.Token) (interface{}, error).

To add jwt-go as a dependency in your Go program, ensure you have Go installed and then run the following command:

go get -u github.com/golang-jwt/jwt/v5

Then, import it in your Go code using:

import "github.com/golang-jwt/jwt/v5"

You can install the jwt CLI tool using the following Go command:

go install github.com/golang-jwt/jwt/v5/cmd/jwt

The jwt command-line tool allows you to sign, verify, and inspect JSON Web Tokens (JWT) directly from your terminal. It supports various signing algorithms and can read/write data via files or stdin.

Modes

You must provide exactly one of the following modes:

• -sign: Create and sign a new token. Use a path to a claims JSON file, - for stdin, or + to use only the -claim arguments provided via CLI.
• -verify: Verify an existing token and output its claims.
• -show: Display the header and claims of a token without verifying the signature.

Example: Sign and Verify a Token

This example creates a token from a JSON object, signs it with an RSA key, and then verifies it using the public key:

echo {"foo":"bar"} | bin/jwt -key test/sample_key -alg RS256 -sign - | bin/jwt -key test/sample_key.pub -verify -

If you previously called Valid() on claims to perform validation outside of the parsing process, you should now use jwt.NewValidator to create a Validator instance.

var v = jwt.NewValidator(jwt.WithLeeway(5*time.Second))
v.Validate(myClaims)

To add custom validation logic to your claims in v5 without bypassing standard validation, implement the ClaimsValidator interface by adding a Validate() error method to your custom claims struct. The library will append any errors returned by your Validate method to the standard validation errors.

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

The ParseFromRequest function (located in the request subpackage) now accepts options to modify parsing behavior.

Common modifiers include:

• WithClaims: Specify custom claims to be used.
• WithParser: Provide a pre-configured Parser instance.