JWT Tokens

The jwt package implements JWS compact serialization (RFC 7515) and JWT claims (RFC 7519) with stdlib-only cryptography — no third-party JOSE dependency. A Verifier is bound to a fixed algorithm allowlist and key material at construction time, so algorithm-confusion attacks (e.g. handing an HS256 token to an RSA verifier) are rejected before any cryptographic operation runs.

Import

import "github.com/thuongh2/go-security/jwt"

Signing

Build a per-algorithm SigningKey, then wrap it in a Signer with an optional key ID (written into the kid header on encode; pass "" to omit it):

// HMAC (shared secret)
signer, err := jwt.NewSigner(jwt.NewHS256([]byte(os.Getenv("JWT_SECRET"))), "key-id")

// RSA (RSASSA-PKCS1-v1_5)
privateKey, _ := rsa.GenerateKey(rand.Reader, 2048)
signer, err := jwt.NewSigner(jwt.NewRS256(privateKey), "")

// ECDSA (fixed-width R||S, not DER)
privateKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
signer, err := jwt.NewSigner(jwt.NewES256(privateKey), "")

// EdDSA (Ed25519)
_, privateKey, _ := ed25519.GenerateKey(rand.Reader)
signer, err := jwt.NewSigner(jwt.EdDSASign(privateKey), "")

Each family also has 384/512 variants: NewHS384/NewHS512, NewRS384/NewRS512, NewES384/NewES512 (P-384/P-521 keys respectively).

Encoding a token

Encode signs a MapClaims set. EncodeRegistered is the ergonomic form: it merges typed RegisteredClaims with any extra custom claims and signs the result.

now := time.Now()
token, err := jwt.EncodeRegistered(signer, jwt.RegisteredClaims{
    Issuer:    "myapp",
    Subject:   "alice",
    Audience:  jwt.Audience{"api.myapp.com"},
    IssuedAt:  jwt.NewNumericDate(now),
    ExpiresAt: jwt.NewNumericDate(now.Add(time.Hour)),
}, jwt.MapClaims{"role": "admin"})
// → "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."

For full control over the claim set, call Encode(signer, claims) directly with a jwt.MapClaims.

Verification

Build a VerifyingKey for the algorithm, then a Verifier. For a single static key, NewVerifierKey is the shortcut:

verifier, err := jwt.NewVerifierKey(jwt.HS256, jwt.NewHS256(secret))

For RSA/ECDSA, build the verifying key from the public key:

verifier, err := jwt.NewVerifierKey(jwt.RS256, jwt.RS256Verify(&privateKey.PublicKey))

Decode verifies the signature and (if a Validator is given) the registered claims, returning claims only on full success:

claims, rc, err := jwt.Decode(token, verifier, validator)
if err != nil {
    // errors.Is(err, jwt.ErrTokenExpired), jwt.ErrSignatureInvalid, etc.
}

For multiple keys (e.g. key rotation), use NewVerifier with an explicit algorithm allowlist and a KeySelector that resolves a key by kid:

verifier, err := jwt.NewVerifier([]jwt.Algorithm{jwt.RS256, jwt.RS384}, mySelector)

Validation options

Validator checks exp/nbf/iat (with clock skew), plus optional issuer/audience requirements — separate from the Verifier, which only checks the signature:

validator := jwt.NewValidator(
    jwt.WithRequiredIssuer("myapp"),
    jwt.WithRequiredAudience("api.myapp.com"),
    jwt.WithLeeway(30*time.Second), // clock skew tolerance; default 60s, max 5m
)

Defaults: system clock, 60s leeway, exp required, issuer/audience unchecked, iat not validated. WithRequireExpiry(false) and WithValidateIAT(true) are also available; see the package for the full list.

JWKS

For verifying tokens signed by an external IdP, JWKSClient fetches a JWK Set from an operator-configured URL, caches it, and implements KeySelector directly — plug it straight into NewVerifier:

jwks, err := jwt.NewJWKSClient("https://issuer.example.com/.well-known/jwks.json")
if err != nil {
    log.Fatal(err)
}

verifier, err := jwt.NewVerifier([]jwt.Algorithm{jwt.RS256}, jwks)

NewJWKSClient fetches the given URL directly — it does not perform OIDC discovery, so pass the JWKS URL itself, not the issuer’s discovery document. The client refreshes on TTL expiry and on a kid miss, throttled by a minimum refresh interval so a burst of unknown-kid requests collapses to one outbound fetch. Options: WithHTTPClient, WithCacheTTL, WithMinRefreshInterval, WithMaxResponseBytes, and AllowInsecureURL(true) (for http:// test fixtures only — the URL must be https:// otherwise). Call jwks.Refresh(ctx) to force an immediate fetch bypassing the throttle.

Supported algorithms

Algorithm	Type	Notes
`HS256`, `HS384`, `HS512`	HMAC	Symmetric — shared secret
`RS256`, `RS384`, `RS512`	RSA-PKCS1v15	Asymmetric — 2048+ bit key
`ES256`, `ES384`, `ES512`	ECDSA	P-256/P-384/P-521; fixed-width R\|\|S, never DER
`EdDSA`	Ed25519	Asymmetric — fast, small

RSA-PSS (PS256/PS384/PS512) is not implemented.

Algorithm confusion protection

A Verifier is built from an explicit algorithm allowlist; a token whose alg header is not in that allowlist — or is "none" — is rejected before any cryptographic operation runs (ErrAlgMismatch / ErrUnsupportedAlg). A key/algorithm mismatch at construction is also an error, not a panic:

_, err := jwt.NewVerifierKey(jwt.RS256, jwt.NewHS256(secret))
// err wraps jwt.ErrKeyTypeMismatch

Error sentinels

Decode/Validate return one of these wrapped sentinels; match with errors.Is:

Error	Meaning
`ErrMalformedToken`	Compact serialization is structurally invalid
`ErrNotJWS`	Not exactly three dot-separated segments
`ErrUnsupportedAlg`	`alg` is `"none"`, empty, or otherwise not supported
`ErrUnsupportedCrit`	Unrecognized critical header parameter
`ErrAlgMismatch`	Token’s `alg` is not in the verifier allowlist
`ErrKeyTypeMismatch`	Key type/curve does not match the algorithm
`ErrSignatureInvalid`	Signature did not verify
`ErrTokenExpired`	Past `exp` (accounting for skew)
`ErrTokenNotYetValid`	`nbf` is in the future
`ErrIssuedInFuture`	`iat` is in the future beyond skew
`ErrClaimMissing`	A required claim is absent
`ErrIssuerMismatch`	`iss` does not match the required value
`ErrAudienceMismatch`	`aud` does not contain the required value
`ErrKeyNotFound`	No configured key matches the token’s `kid`

MapClaims

Decode already returns typed RegisteredClaims (rc.Subject, rc.ExpiresAt, …) alongside the raw MapClaims for custom fields:

claims, rc, err := jwt.Decode(token, verifier, validator)

sub := rc.Subject                       // typed registered claim
scopes, _ := claims.GetStringSlice("roles")
role, _ := claims["role"].(string)      // custom claim, untyped

MapClaims also exposes GetString, Audience(), and Registered() (re-derives RegisteredClaims from the map).

Use with authn.BearerTokenProvider

Wire a verified bearer token into authn.Manager alongside password/API-key providers via web/resource’s BearerTokenAuthenticator:

tokenAuth := resource.NewBearerTokenAuthenticator(verifier, validator, resource.DefaultClaimsMapper())

manager := authn.NewManager([]authn.Provider{
    authn.NewBearerTokenProvider(tokenAuth),
})

Use with web/resource server

See resource server for the RequireBearer middleware that reads the Authorization: Bearer ... header and authenticates via JWT (or opaque-token introspection).

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Import

Signing

Encoding a token

Verification

Validation options

JWKS

Supported algorithms

Algorithm confusion protection

Error sentinels

MapClaims

Use with authn.BearerTokenProvider

Use with web/resource server

​Import

​Signing

​Encoding a token

​Verification

​Validation options

​JWKS

​Supported algorithms

​Algorithm confusion protection

​Error sentinels

​MapClaims

​Use with authn.BearerTokenProvider

​Use with web/resource server

Import

Signing

Encoding a token

Verification

Validation options

JWKS

Supported algorithms

Algorithm confusion protection

Error sentinels

MapClaims

Use with authn.BearerTokenProvider

Use with web/resource server