Vert.x WebSocket + JWTAuthHandler: enforcing least-privilege after a token expires mid-connection

Question

We are integrating vertx-auth-jwt with a Vert.x 4.x HTTP server that upgrades some routes to long-lived WebSocket connections. Initial authentication works: JWTAuthHandler validates the signature and standard claims, and per-route AuthorizationHandler instances enforce PermissionBasedAuthorization so each endpoint only requires the one permission it needs.

The unresolved part is what should happen when the JWT's exp passes while the WebSocket is still open. As far as we can tell, the handler only authenticates the upgrade request, so the connection appears to stay authorized indefinitely with the permissions captured at handshake time. That conflicts with our least-privilege goal, since a user's permissions may be revoked or narrowed before the token expires.

We also see occasional premature rejections that we suspect come from clock skew between the token issuer and the Vert.x validator, but we have not confirmed whether a leeway option exists for our exact vertx-auth-jwt version.

Is there a documented or idiomatic way in Vert.x 4.x to re-evaluate authentication or permissions on an established WebSocket when the token expires, or is periodic re-authentication entirely the application's responsibility? Does vertx-auth-jwt expose configurable clock-skew leeway for exp validation in recent 4.x releases? And if we close the socket on expiry, what is the recommended way to signal the reason to the client?

Tasadduq Burney · Answer

Answer to the exact questionVert.x’s JWTAuthHandler runs only during the HTTP upgrade that creates the WebSocket; after the socket is open it does not re‑validate the JWT, so the permissions captured at handshake time remain in effect until the connection is closed.Confirmed factsThe handler validates the JWT signature and standard claims (including exp) during the upgrade request.Vert.x JWT auth provides a configurable clock‑skew leeway via JWTAuthOptions.setClockSkew(long milliseconds) (available in vertx‑auth‑jwt 4.x).No built‑in mechanism automatically drops a WebSocket when the token’s exp passes.Likely explanationBecause the handler does not schedule any periodic check, the server trusts the initial authentication for the lifetime of the socket. Therefore, enforcing least‑privilege after the token expires is the application’s responsibility.Steps to enforce least‑privilegeWhen creating the JWTAuthHandler, set an appropriate clockSkew if your issuer and validator clocks may differ:JWTAuthOptions opts = new JWTAuthOptions().setClockSkew(15000L); // 15 s leeway
JWTAuthProvider jwtAuth = JWTAuth.create(vertx, opts);
After the WebSocket upgrade, store the token’s exp claim (or the User object) where your frame handler can access it.In your WebSocketHandler (or a periodic timer), compare the current epoch‑seconds to the stored exp:long now = System.currentTimeMillis() / 1000;
if (now >= exp) {
    ws.close(1008, "Token expired"); // 1008 = Policy Violation
}
Choose a close code that reflects the reason. The WebSocket spec recommends 1008 for authentication‑policy violations; you may also use a private range code (e.g., 4401) with a short reason phrase if you need more detail for the client.Missing diagnostic detailPlease confirm the version of vertx-auth-jwt you are using; the setClockSkew method is available from 4.0.0 onward. If you are on an earlier version, you will need to upgrade or handle leeway manually.

Vert.x WebSocket + JWTAuthHandler: enforcing least-privilege after a token expires mid-connection

1 answer

Answer to the exact question

Confirmed facts

Likely explanation

Steps to enforce least‑privilege

Missing diagnostic detail

Your perspective belongs here.

0 question comments