Br Jwks Jwt Auth

better-route: JWKS JWT auth

Use this for OIDC/OAuth-style bearer JWTs signed with asymmetric keys. In better-route 0.6.0 the library ships Rs256JwksJwtVerifier, so do not write a custom verifier for normal RS256 or ES256 JWKS use cases.

Pattern

use BetterRoute\Middleware\Auth\BearerTokenAuthMiddleware;
use BetterRoute\Middleware\Auth\JwtBearerTokenVerifierAdapter;
use BetterRoute\Middleware\Jwt\HttpJwksProvider;
use BetterRoute\Middleware\Jwt\Rs256JwksJwtVerifier;

$jwks = new HttpJwksProvider(
    jwksUri: 'https://issuer.example.com/.well-known/jwks.json',
    ttlSeconds: 3600,
    issuer: 'https://issuer.example.com'
);

$verifier = new Rs256JwksJwtVerifier(
    jwks: $jwks,
    leewaySeconds: 60,
    expectedIssuer: 'https://issuer.example.com',
    expectedAudience: 'my-api',
    requireExpiration: true,
    maxLifetimeSeconds: 3600,
    allowedAlgorithms: ['RS256']
);

$auth = new BearerTokenAuthMiddleware(
    verifier: new JwtBearerTokenVerifierAdapter($verifier),
    requiredScopes: ['orders:read']
);

For write routes, still call ->protectedByMiddleware('bearerAuth') so WordPress dispatches to the middleware pipeline.

Critical rules

• kid in the JOSE header is required and must match exactly one usable JWKS key.
• On kid miss, the verifier calls JwksProviderInterface::refresh() once, then fails closed.
• Never fall back to "try every public key"; that accepts stale or unrelated keys.
• allowedAlgorithms supports RS256 and ES256; none and HS* are rejected even if accidentally configured.
• HttpJwksProvider requires an https URI and uses sslverify => true.
• Private JWK fields are stripped by JwksKeySanitizer; JWKS should contain public keys only.
• Set expectedIssuer and expectedAudience in production.
• Keep requireExpiration: true; disabling it is a migration-only decision.

JWKS cache invalidation

HttpJwksProvider listens for:

do_action('better_route/jwks_refresh', 'https://issuer.example.com');

Use this from admin tooling after key rotation or when forcing a cache clear.

Tests

Use StaticJwksProvider for unit tests:

$verifier = new Rs256JwksJwtVerifier(
    new StaticJwksProvider([$publicJwk]),
    now: static fn (): int => 1700000000
);

Cross-references

• Use br-auth-middleware for generic auth middleware choice and protectedByMiddleware() route intent.
• Use br-error-contract for the 401 invalid_token response shape.
• Use br-crypto when generating nonces, state, PKCE values, or doing token-bound string compares.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lonsdale201
• Source: Lonsdale201/wp-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.