extractConfirmationClaim extracts the cnf (confirmation) claim from the token string. This claim is used for DPoP (Demonstrating Proof-of-Possession)

hasAnyTrustedHeaders returns true if any header trust flags are enabled

HasClaims checks if claims exist in the context without retrieving them.

HasDPoPContext checks if a DPoP context exists in the context. Returns true for DPoP-bound tokens, false for Bearer tokens. Example usage: if core.

IssuerFromContext extracts the issuer from the context. This is useful for JWKS providers that need to route requests based on the issuer. Note: The

MultiTokenExtractor returns a TokenExtractor that runs multiple TokenExtractors and takes the one that does not return an empty token. If a TokenExtra

WithCustomClient sets a custom HTTP client for the Provider. If not specified, a default client with 30s timeout is used.

WithCustomJWKSURI sets a custom JWKS URI for the Provider. When set, the Provider will fetch JWKS directly from this URI, skipping the OIDC discovery

WithExcludedMethods excludes specific gRPC methods from JWT validation. Methods should be provided in the format: "/package.Service/Method" For more

WithMultiIssuerCacheTTL sets the cache refresh interval for all per-issuer providers. If not specified, defaults to 15 minutes. The TTL determines th

WithRegisteredClaimsValidator sets a validation function that runs against the registered claims (iss, sub, aud, exp, nbf, iat, jti) after standard va

WithValidateOnOptions sets whether OPTIONS requests should have their JWT validated. Default: true (OPTIONS requests are validated)

assertErrorResponse asserts the HTTP status, JSON error body, and WWW-Authenticate header.

buildSymmetricKeySet creates a jwk.Set containing a symmetric key with the specified algorithm and optional key ID. This allows symmetric keys to be h

calculateJKT computes the JWK thumbprint using SHA-256 per RFC 7638. The thumbprint is base64url-encoded without padding.

Try it out with: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnby1qd3QtbWlkZGxld2FyZS1leGFtcGxlIiwiYXVkIjoiYXVkaWVuY2UtZXhhbXBsZSIsInN1YiI6IjEyMzQ

CookieTokenExtractor builds a TokenExtractor that takes a request and extracts the token from the cookie using the passed in cookieName. Note: Cookies

Health check (no authentication required)

WithCredentialsOptional allows requests without JWT tokens to proceed. When set to true, requests without tokens will not return an error, but the con

WithIssuerKeyConfigs configures symmetric keys for multiple issuers at once. This is the batch equivalent of WithIssuerKeyConfig, following the same p

algToJWX maps validator.SignatureAlgorithm to jwa.SignatureAlgorithm for symmetric algorithms. This is a local helper to avoid importing the validator

============================================================================= Helper Functions =======================================================

extractCustomClaims extracts and validates custom claims from the token string. SDK-agnostic approach: Manually decodes JWT payload for maximum portab

generateTestToken creates a test JWT token with the given issuer, audience, and signing key. The token expires in 1 hour to prevent expiration issues

validateAudience checks if the token audiences contain at least one expected audience.

DPoPHeaderExtractor extracts the DPoP proof from the "DPoP" HTTP header. Returns empty string if the header is not present (which is valid for Bearer

DefaultErrorHandler is the default error handler implementation. It provides structured error responses with appropriate HTTP status codes and RFC 675

WithCache sets a custom Cache implementation for the CachingProvider. This allows users to provide their own caching strategy (e.g., Redis-backed cach

WithErrorHandler sets the handler called when errors occur during JWT validation. See the ErrorHandler type for more information. Default: DefaultErr

WithErrorHandler sets a custom error handler function. Default is DefaultErrorHandler which maps errors to gRPC status codes.

WithExclusionHandler sets a function that dynamically determines whether a gRPC method should be excluded from JWT validation. The handler receives th

WithMultiIssuerCache sets a custom Cache implementation for all per-issuer providers. This allows users to provide their own caching strategy (e.g., R

WithStandardProxy configures trust for standard reverse proxies (Nginx, Apache, HAProxy). Trusts X-Forwarded-Proto and X-Forwarded-Host headers. Use t

WithTokenExtractor sets a custom token extractor function. Default is MetadataTokenExtractor which extracts from "authorization" metadata.

buildBareWWWAuthenticateHeaders builds bare WWW-Authenticate headers without error codes. Per RFC 6750 Section 3.1, when a request lacks authenticatio

buildTestToken builds a signed HS256 JWT with the given claims.

getLeftmost extracts the leftmost value from a comma-separated header. This handles multiple proxies: "value1, value2, value3" -> "value1" The leftmos

parseToken parses and performs basic validation on the token. Abstraction point: This method wraps the underlying JWT library's parsing.

Try it out with: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnby1qd3QtbWlkZGxld2FyZS1leGFtcGxlIiwiYXVkIjoiYXVkaWVuY2UtZXhhbXBsZSIsInN1YiI6IjEyMzQ

Try it out with: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnby1qd3QtbWlkZGxld2FyZS1leGFtcGxlIiwiYXVkIjoiYXVkaWVuY2UtZXhhbXBsZSIsInN1YiI6IjEyMzQ

validateIssuer checks if the token issuer matches one of the expected issuers.

Error implements the error interface.

GetConfirmationJKT returns the jkt from the cnf claim, or empty string if not present. This method implements the core.TokenClaims interface.

GetHTM returns the HTTP method (htm) from the DPoP proof.

GetHTU returns the HTTP URI (htu) from the DPoP proof.

HasConfirmation returns true if the token has a cnf claim. This method implements the core.TokenClaims interface.

ParameterTokenExtractor returns a TokenExtractor that extracts the token from the specified query string parameter. Note: Query parameters do not carr

Stats returns observability information about all managed issuers. This includes both OIDC providers (dynamically cached) and symmetric issuers (stati

WithDPoPIATLeeway sets the clock skew allowance for future iat claims in DPoP proofs. This allows DPoP proofs with iat timestamps slightly in the futu

WithDPoPProofOffset sets the maximum age offset for DPoP proofs. This determines how far in the past a DPoP proof's iat timestamp can be. Default: 30

buildDPoPWWWAuthenticateHeaders builds WWW-Authenticate headers for DPoP-specific errors.

Helper functions

Helper functions

createDPoPProofWithAccessTokenAndTime creates a DPoP proof with ATH claim and specified timestamp

createDPoPProofWithOptions creates a DPoP proof with configurable algorithm and timestamp

extractDPoPClaims extracts DPoP-specific claims from the JWT payload.

normalizePort normalizes the host by stripping default ports per RFC 3986 Section 6.2.3. This is required for DPoP HTU validation to avoid false misma

stringToJWXAlgorithm converts our string algorithm to jwx's jwa.SignatureAlgorithm.

timeToUnix converts a time.Time to Unix timestamp, returning 0 for zero time.

GetDPoPContext retrieves the DPoP context from the request context. Returns nil if no DPoP context exists (e.g., for Bearer tokens). This is a conven

HasClaims checks if claims exist in the context. Example: if jwtmiddleware.HasClaims(r.Context()) { claims, _ := jwtmiddleware.GetClaims[*vali

HasDPoPContext checks if a DPoP context exists in the request context. Returns true for DPoP-bound tokens, false for Bearer tokens. This is a conveni

WithAPIGatewayProxy configures trust for API gateways (AWS API Gateway, Kong, Traefik). Trusts X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Pr

WithDPoPIATLeeway sets the clock skew allowance for DPoP proof iat claims. This allows DPoP proofs with iat timestamps slightly in the future due to c

WithDPoPProofOffset sets the maximum age for DPoP proofs. This determines how far in the past a DPoP proof's iat timestamp can be. Default: 300 secon

WithMultiIssuerHTTPClient sets a custom HTTP client for all per-issuer providers. If not specified, a default client with 30s timeout is used. Exampl

WithRFC7239Proxy configures trust for RFC 7239 Forwarded header. This is the most secure option if your proxy supports the structured Forwarded header

addIssuerKeyConfig validates and stores a single issuer key configuration. Shared by WithIssuerKeyConfig and WithIssuerKeyConfigs.

convertAuthScheme converts middleware AuthScheme to core.AuthScheme

evictLRU removes the least-recently-used provider from the cache. Must be called with write lock held.

fetchWithCacheControl fetches JWKS and extracts TTL from Cache-Control headers. Returns the JWKS set, the TTL (or 0 if not present), and any error.

generateToken creates a JWT token for testing

getDPoPMode returns the DPoP mode from the middleware. Returns the configured mode or DPoPAllowed as default.

handleBearerToken processes Bearer token validation logic. The authScheme parameter is used for logging purposes to distinguish between true Bearer to

isExcluded checks if a gRPC method should skip JWT validation. It checks the static excluded methods set first, then the dynamic exclusion handler.

isSymmetricAlgorithm returns true if the algorithm is a symmetric (HMAC) algorithm.

logWarn logs a warning message if the logger is configured.

normalizeHost returns the hostname:port with default ports stripped, so that "example.com" and "example.com:443" compare equal for HTTPS.

parseCacheControl extracts max-age from Cache-Control header with security validation. Returns 0 if max-age is not present, invalid, or unreasonable.

parseForwardedHeader parses RFC 7239 Forwarded header. Example: "for=192.0.2.60;proto=https;host=api.example.com" Returns extracted scheme and host.

validateRequest extracts and validates the JWT from the context.

Error returns a string representation of the error.

GetATH returns the access token hash (ath) from the DPoP proof, if present. Returns empty string if the ath claim is not included in the proof.

GetConfirmationJKT returns the jkt from the cnf claim, or empty string if not present.

GetHTM returns the HTTP method (htm) from the DPoP proof. This method implements the core.DPoPProofClaims interface.

GetHTU returns the HTTP URI (htu) from the DPoP proof. This method implements the core.DPoPProofClaims interface.

GetIAT returns the issued-at timestamp (iat) from the DPoP proof.

GetIAT returns the issued-at timestamp (iat) from the DPoP proof. This method implements the core.DPoPProofClaims interface.

GetJTI returns the unique identifier (jti) of the DPoP proof. This method implements the core.DPoPProofClaims interface.