v1.0.3
Home GitHub

Architecture

Last updated


This page shows how go-jwt's layers relate in a single diagram; per-module flows, sequence diagrams, and the state machine live in doc/architecture.md.

System Overview


graph TB
    subgraph Application
        GIN[GinMiddleware]
        HTTP[HTTPMiddleware]
        APP[Custom Handler]
    end

    subgraph JWTAuth
        CREATE[Create]
        VERIFY[Verify]
        REFRESH[refresh]
        REVOKE[Revoke]
        FP[Device Fingerprint]
        COOKIE[Cookie Management]
    end

    NEW[New] --> JWTAuth
    GIN --> VERIFY
    HTTP --> VERIFY
    APP --> CREATE
    APP --> REVOKE
    VERIFY -->|Access Token expired or missing| REFRESH
    REFRESH -->|Over threshold| CREATE
    CREATE --> FP
    VERIFY --> FP
    CREATE --> COOKIE
    REFRESH --> COOKIE
    REVOKE --> COOKIE
    NEW --> PEM[(ECDSA P-256 Keys)]
    JWTAuth --> REDIS[(Redis)]
  1. graph TB
  2.     subgraph Application
  3.         GIN[GinMiddleware]
  4.         HTTP[HTTPMiddleware]
  5.         APP[Custom Handler]
  6.     end
  8.     subgraph JWTAuth
  9.         CREATE[Create]
  10.         VERIFY[Verify]
  11.         REFRESH[refresh]
  12.         REVOKE[Revoke]
  13.         FP[Device Fingerprint]
  14.         COOKIE[Cookie Management]
  15.     end
  17.     NEW[New] --> JWTAuth
  18.     GIN --> VERIFY
  19.     HTTP --> VERIFY
  20.     APP --> CREATE
  21.     APP --> REVOKE
  22.     VERIFY -->|Access Token expired or missing| REFRESH
  23.     REFRESH -->|Over threshold| CREATE
  24.     CREATE --> FP
  25.     VERIFY --> FP
  26.     CREATE --> COOKIE
  27.     REFRESH --> COOKIE
  28.     REVOKE --> COOKIE
  29.     NEW --> PEM[(ECDSA P-256 Keys)]
  30.     JWTAuth --> REDIS[(Redis)]

Layers


LayerComponentsFilesResponsibility
IntegrationGinMiddleware, HTTPMiddleware, GetAuthDataFromGinContext, GetAuthDataFromHTTPRequestcore/middleware.goCall Verify; respond with a JSON error on failure, put *Auth into the context on success
LifecycleCreate, Verify, refresh, Revokecore/create.go, core/verify.go, core/refresh.go, core/revoke.goIssue, verify, refresh, revoke
BindinggetFingerprint, getAccessToken, getRefreshIDcore/utility.go, core/refreshData.goExtract credentials and the device fingerprint from the request
DeliverysetCookie, clearCookiecore/cookie.goWrite or clear cookies according to Config.Cookie
InitializationNew, handlePEM, parsePEMcore/instance.go, core/pem.goApply defaults, load or generate keys, connect to Redis
StateRedis—Refresh data, JTI whitelist, revocation records, refresh locks

Cross-Cutting Principles


PrincipleImplementation
Check server state beyond the signatureAfter ES256 verification, an Access Token is valid only while jti:<jti> exists in Redis
Bind credentials to the deviceThe Access Token fp claim and the fp in Redis refresh data must both equal the fingerprint computed for this request
Never split multi-key writesIssue, refresh, and revoke send their Redis writes in one TxPipeline (MULTI/EXEC)
Refresh a Refresh ID once at a timeA 3-second SETNX lock:refresh:<id> lock, released by a Lua script that DELs only when the holder matches
Results instead of errorsEvery lifecycle method returns JWTAuthResult, distinguishing causes by StatusCode/ErrorTag

Dependencies


ModuleVersion (go.mod)Used for
github.com/golang-jwt/jwt/v5v5.2.2ES256 signing (jwt.SigningMethodES256) and parsing with signature, exp, and nbf validation; go-jwt adds the Refresh ID, fingerprint, JTI whitelist, refresh, and revocation on top
github.com/redis/go-redis/v9v9.8.0All session state, TxPipeline writes, and the unlock EVAL
github.com/gin-gonic/ginv1.10.1GinMiddleware() and GetAuthDataFromGinContext()


Other Go JWT packages, quoted from their GitHub descriptions (2026-10-21); the right column describes only go-jwt's own behavior.
PackageDescription (GitHub)go-jwt
appleboy/gin-jwtJWT Middleware for Gin frameworkServes both Gin (GinMiddleware) and net/http (HTTPMiddleware); refresh runs inside Verify, so there is no refresh endpoint to call
auth0/go-jwt-middlewareA Middleware for Go Programming Language to check for JWTs on HTTP requestsAlso issues (Create) and revokes (Revoke) tokens, and requires the jti to exist in Redis after the signature check
go-chi/jwtauthJWT authentication middleware for Go HTTP servicesBinds every Access Token to a device fingerprint and to a Refresh ID whose data lives in Redis
lestrrat-go/jwxComplete implementation of JWx (JOSE) technologies for GoSigns only ES256 and covers the login session lifecycle: issue, verify, refresh, revoke

Further Reading


中文