Skip to main content

Auth Overview

Built-in auth middleware provides bridge patterns for WordPress REST routes.

Available middleware​

  • BetterRoute\Middleware\Jwt\JwtAuthMiddleware
  • BetterRoute\Middleware\Jwt\Rs256JwksJwtVerifier (v0.6.0) — RS256/ES256 verifier backed by JWKS; see JWKS (RS256 / ES256)
  • BetterRoute\Middleware\Jwt\HttpJwksProvider / StaticJwksProvider (v0.6.0)
  • BetterRoute\Middleware\Auth\BearerTokenAuthMiddleware
  • BetterRoute\Middleware\Auth\HmacSignatureMiddleware (v0.6.0) — HMAC request signatures with replay-window enforcement; see HMAC Request Signatures
  • BetterRoute\Middleware\Auth\CookieNonceAuthMiddleware
  • BetterRoute\Middleware\Auth\ApplicationPasswordAuthMiddleware
  • BetterRoute\Middleware\Auth\WpClaimsUserMapper
  • BetterRoute\Middleware\Auth\OwnershipGuardMiddleware (v0.5.0) — see Ownership guards

Context propagation​

On success, middleware writes auth context attributes:

  • auth (provider, userId, subject, scopes)
  • optionally claims, userId, user, scopes
  • hmac (v0.6.0) — keyId and algorithm after successful HMAC signature verification
  • singleUseToken (v0.6.0) — issuer-supplied context after a single-use token is consumed

Important policy note​

Even with auth middleware, route registration still requires explicit permission_callback (by design in dispatcher integration). For middleware-authenticated routes, declare the intent with ->protectedByMiddleware(...) (since 0.4.0). For routes guarded by HMAC or single-use tokens (no WordPress user behind them), use ->publicRoute() and let the middleware be the gate.

v0.6.0 additions​

  • Asymmetric JWT. Rs256JwksJwtVerifier plus HttpJwksProvider and StaticJwksProvider for OIDC-style providers. Strict kid matching, algorithm pinning, private-field stripping. See JWKS (RS256 / ES256).
  • HMAC request signatures. HmacSignatureMiddleware plus HmacSecretProviderInterface and ArrayHmacSecretProvider. Canonical input, replay window, multi-key rotation. See HMAC Request Signatures.
  • Single-use tokens. SingleUseTokenMiddleware plus three stores. See Single-Use Tokens.

v0.5.0 additions​

  • OwnershipGuardMiddleware for routes where the authenticated user may only access their own object. Default deniedStatus is 404 to avoid leaking existence.
  • Resource\OwnedResourcePolicy::currentUserOwns() — Resource DSL preset that wires the URL id, the auth identity, and an optional bypassCapability together. See Ownership guards.

v0.3.0 hardening​

  • Hs256JwtVerifier requires exp by default and supports expectedIssuer, expectedAudience, maxLifetimeSeconds, and maxTokenLength. See JWT and Bearer.
  • WpClaimsUserMapper removed 'sub' from default idClaims — re-add it explicitly when needed.
  • BearerTokenAuthMiddleware no longer leaks the verifier exception message; failed tokens uniformly return 401 invalid_token with no details.reason.

Common mistakes​

  • Relying on middleware alone without route permissions
  • Missing Authorization header normalization
  • Not mapping JWT/Bearer claims to WP user where needed

Validation checklist​

  • 401 on missing/invalid credential
  • 403 on missing required scopes
  • expected auth attributes exist in RequestContext