go-chi/jwtauth

Once the jwtauth.Verifier has processed a request, you can access the decoded token and its claims within your HTTP handlers using jwtauth.FromContext(r.Context()).

_, claims, err := jwtauth.FromContext(r.Context())
if err != nil {
    // handle error
}
// use claims["key"]

After Verifier has run, you can access the parsed JWT token and its claims within your handlers using FromContext. This function returns the jwt.Token, a map[string]interface{} containing the claims, and any error encountered during verification.

func MyHandler(w http.ResponseWriter, r *http.Request) {
    token, claims, err := jwtauth.FromContext(r.Context())
    if err != nil {
        // Handle error (e.g., token expired)
        return
    }
    
    // Access a specific claim
    userID := claims["sub"]
    fmt.Fprintf(w, "Hello, %v", userID)
}

You can manually manage tokens using the Encode and Decode methods on a *JWTAuth instance.

• Encode(claims map[string]interface{}): Creates a new signed JWT string from a map of claims.
• Decode(tokenString string): Parses and verifies a raw JWT string.

// Encoding
claims := map[string]interface{}{"sub": "12345", "name": "John Doe"}
token, tokenString, err := ja.Encode(claims)

// Decoding
token, err := ja.Decode(tokenString)

To use jwtauth, you must first create a *JWTAuth instance using New(). This instance holds your signing algorithm, keys, and validation options.

If you are using asymmetric algorithms (like RSA or ECDSA), provide the public key as the verifyKey. For symmetric algorithms (like HMAC), the signKey is used for both signing and verification.

// Example for HMAC (Symmetric)
ja := jwtauth.New("HS256", []byte("secret"), nil)

// Example for RSA (Asymmetric)
ja := jwtauth.New("RS256", privateKey, publicKey)

If you need to support token extraction from sources other than the default (Header and Cookie), use Verify() instead of Verifier(). You can pass custom functions that satisfy the signature func(r *http.Request) string to define where to look for the token.

// Example: Look in Query param first, then Header
r.Use(jwtauth.Verify(ja, jwtauth.TokenFromQuery, jwtauth.TokenFromHeader))

The Verifier middleware is responsible for finding a JWT in an incoming request and verifying its signature and validity. It does not block the request; instead, it attaches the resulting jwt.Token and any error to the request context.

Verifier searches for tokens in this order:

1. Authorization: BEARER <token> header
2. Cookie named jwt

It always calls the next handler in the chain. You must follow Verifier with either Authenticator or a custom handler to decide how to respond to invalid tokens.

// Standard usage with default token locations (Header then Cookie)
r.Use(jwtauth.Verifier(ja))

The Authenticator middleware is used to enforce authentication. It checks the request context for a valid token provided by a preceding Verifier middleware.

If the token is missing or invalid (based on the error stored in the context), Authenticator returns a 401 Unauthorized response and stops the chain. If the token is valid, it calls the next handler.

// Typical middleware chain
r.Use(jwtauth.Verifier(ja))
r.Use(jwtauth.Authenticator(ja))

r.Get("/protected", func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Access granted!"))
})

The package provides several helpers to simplify setting standard JWT claims like iat (Issued At), exp (Expiration), and nbf (Not Before) using Unix timestamps.

claims := map[string]interface{}{}

// Set 'iat' to current time
jwtauth.SetIssuedNow(claims)

// Set 'exp' to 1 hour from now
jwtauth.SetExpiryIn(time.Hour)

// Set 'exp' to a specific time
jwtauth.SetExpiry(claims, someTime)

The following error variables are used to identify specific authentication failures when calling FromContext or VerifyToken.

var (
	ErrUnauthorized = errors.New("token is unauthorized")
	ErrExpired      = errors.New("token is expired")
	ErrNBFInvalid   = errors.New("token nbf validation failed")
	ErrIATInvalid   = errors.New("token iat validation failed")
	ErrNoTokenFound = errors.New("no token found")
	ErrAlgoInvalid  = errors.New("algorithm mismatch")
)