or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

claims.mdindex.mdkey-parsing.mdrequest-extraction.mdsigning-methods.mdtoken-creation.mdtoken-parsing.md
tile.json

index.mddocs/

JWT - JSON Web Tokens for Go

A comprehensive Go implementation of JSON Web Tokens (JWT) as specified in RFC 7519. This library enables developers to create, parse, verify, sign, and validate JWTs for authentication and authorization purposes.

Package Information

  • Package Name: github.com/golang-jwt/jwt/v5
  • Package Type: golang
  • Language: Go
  • Version: 5.3.0
  • Installation: go get -u github.com/golang-jwt/jwt/v5
  • License: MIT

Core Imports

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

For HTTP request extraction utilities:

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

Basic Usage

Creating and Signing a Token

import (
    "fmt"
    "time"
    "github.com/golang-jwt/jwt/v5"
)

// Create claims
claims := jwt.RegisteredClaims{
    Issuer:    "my-app",
    Subject:   "user123",
    ExpiresAt: jwt.NewNumericDate(time.Now().Add(24 * time.Hour)),
    IssuedAt:  jwt.NewNumericDate(time.Now()),
}

// Create token with claims
token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)

// Sign token with secret key
secretKey := []byte("my-secret-key")
signedToken, err := token.SignedString(secretKey)
if err != nil {
    panic(err)
}

fmt.Println("Signed token:", signedToken)

Parsing and Validating a Token

import (
    "fmt"
    "github.com/golang-jwt/jwt/v5"
)

// Parse and validate token
tokenString := "eyJhbGc..."
secretKey := []byte("my-secret-key")

token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
    // Validate the signing method
    if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
        return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
    }
    return secretKey, nil
})

if err != nil {
    panic(err)
}

if claims, ok := token.Claims.(jwt.MapClaims); ok && token.Valid {
    fmt.Println("Token is valid!")
    fmt.Println("Claims:", claims)
}

Architecture

The JWT library is organized into several key components:

Core Components

  1. Token Management - Create, sign, parse, and validate JWT tokens
  2. Claims - Structured and map-based claims implementations
  3. Signing Methods - Support for multiple cryptographic algorithms
  4. Parser - Flexible token parsing with validation options
  5. Validator - Standalone claims validation
  6. Key Utilities - PEM key parsing for various algorithms
  7. Request Extraction - HTTP request token extraction utilities

Security Features

  • Algorithm verification to prevent algorithm confusion attacks
  • Configurable validation options for claims
  • Support for custom signing methods
  • Time-based validation with configurable leeway
  • Protection against unsecured JWTs (none algorithm)

Capabilities

Token Creation and Signing

Create JWT tokens with various claims types and sign them using multiple algorithms including HMAC, RSA, RSA-PSS, ECDSA, and EdDSA.

func New(method SigningMethod, opts ...TokenOption) *Token
func NewWithClaims(method SigningMethod, claims Claims, opts ...TokenOption) *Token

Token Creation and Signing

Token Parsing and Validation

Parse JWT token strings, validate signatures, and verify claims with comprehensive validation options.

func Parse(tokenString string, keyFunc Keyfunc, options ...ParserOption) (*Token, error)
func ParseWithClaims(tokenString string, claims Claims, keyFunc Keyfunc, options ...ParserOption) (*Token, error)

Token Parsing and Validation

Claims Management

Handle JWT claims using structured RegisteredClaims or flexible MapClaims, with support for custom claims implementations.

type Claims interface {
    GetExpirationTime() (*NumericDate, error)
    GetIssuedAt() (*NumericDate, error)
    GetNotBefore() (*NumericDate, error)
    GetIssuer() (string, error)
    GetSubject() (string, error)
    GetAudience() (ClaimStrings, error)
}

type RegisteredClaims struct {
    Issuer    string
    Subject   string
    Audience  ClaimStrings
    ExpiresAt *NumericDate
    NotBefore *NumericDate
    IssuedAt  *NumericDate
    ID        string
}

type MapClaims map[string]any

Claims Types and Handling

Signing Methods

Support for multiple signing algorithms with pre-configured instances for each algorithm variant.

type SigningMethod interface {
    Verify(signingString string, sig []byte, key any) error
    Sign(signingString string, key any) ([]byte, error)
    Alg() string
}

Available algorithms:

  • HMAC: HS256, HS384, HS512
  • RSA: RS256, RS384, RS512
  • RSA-PSS: PS256, PS384, PS512
  • ECDSA: ES256, ES384, ES512
  • EdDSA: Ed25519

Signing Methods and Algorithms

Key Parsing Utilities

Parse cryptographic keys from PEM-encoded formats for use with signing and verification.

func ParseRSAPrivateKeyFromPEM(key []byte) (*rsa.PrivateKey, error)
func ParseRSAPublicKeyFromPEM(key []byte) (*rsa.PublicKey, error)
func ParseECPrivateKeyFromPEM(key []byte) (*ecdsa.PrivateKey, error)
func ParseECPublicKeyFromPEM(key []byte) (*ecdsa.PublicKey, error)
func ParseEdPrivateKeyFromPEM(key []byte) (crypto.PrivateKey, error)
func ParseEdPublicKeyFromPEM(key []byte) (crypto.PublicKey, error)

Key Parsing Utilities

HTTP Request Token Extraction

Extract JWT tokens from HTTP requests using various strategies including Authorization headers, query parameters, and custom extractors.

func ParseFromRequest(req *http.Request, extractor Extractor, keyFunc jwt.Keyfunc, options ...ParseFromRequestOption) (token *jwt.Token, err error)

type Extractor interface {
    ExtractToken(*http.Request) (string, error)
}

HTTP Request Token Extraction

Common Use Cases

  • Authentication Systems - Issue and verify JWT tokens for user authentication
  • OAuth 2.0 Bearer Tokens - Implement OAuth 2.0 token-based authorization
  • API Security - Secure REST APIs with JWT-based access control
  • Microservices Authorization - Share authentication across distributed services
  • Single Sign-On (SSO) - Enable SSO with JWT tokens across applications

Error Handling

The library provides comprehensive error types for different failure scenarios:

var (
    ErrInvalidKey                error
    ErrInvalidKeyType            error
    ErrHashUnavailable           error
    ErrTokenMalformed            error
    ErrTokenUnverifiable         error
    ErrTokenSignatureInvalid     error
    ErrTokenRequiredClaimMissing error
    ErrTokenInvalidAudience      error
    ErrTokenExpired              error
    ErrTokenUsedBeforeIssued     error
    ErrTokenInvalidIssuer        error
    ErrTokenInvalidSubject       error
    ErrTokenNotValidYet          error
    ErrTokenInvalidId            error
    ErrTokenInvalidClaims        error
    ErrInvalidType               error
)

Configuration

Time Precision

Control the precision of timestamps in JWT tokens:

var TimePrecision time.Duration

Default: time.Second (no fractional timestamps)

Audience Claim Serialization

Control how single-element audience arrays are serialized:

var MarshalSingleStringAsArray bool

Default: true (always serialize as array)