Recommended pattern to refresh a client JWT via getToken when using connect/refresh proxy

[vishveshyadav]

Hello,

I would like to understand the recommended way to combine the client-side getToken callback with the connect/refresh proxy model.

My setup

• This runs in a browser client, and we do not use cookies. The JWT is passed explicitly via the getToken callback, not through a cookie.
• On the client I have a getToken callback that returns a short-lived JWT (valid for ~5 minutes).
• I invoke getToken and pass that token along with the Centrifugo connection request, which goes through a connect proxy.
• My connect proxy backend verifies the token and establishes a server-side subscription.
• When the token is about to expire, the refresh proxy is triggered. However, the refresh proxy only has access to the same token that was sent with the initial connect request, not a freshly issued one.

Question

Is there a way for the client's getToken callback to be re-invoked when the refresh proxy triggers, so the client can supply a newly issued token for the refresh? More generally, what is the recommended pattern for refreshing a client-issued JWT in a connect/refresh proxy setup?

What I currently do (and would like to avoid)

On every refresh event I explicitly expire the connection. This causes a disconnect, and when the SDK attempts to reconnect it invokes getToken again and obtains a fresh token. This works, but the "expire then fully reconnect" cycle feels like unnecessary overhead. I would prefer a pattern that refreshes the token without tearing down the connection.

Environment

• Centrifugo server: v6.7
• centrifuge-js: 5.7.0
• Browser client, no cookies

Thanks in advance for any guidance.

[FZambia]

Hi @vishveshyadav,

Short answer: getToken is not re-invoked when the refresh proxy fires, and that's by design — Centrifugo has two alternative connection-expiration models, and enabling the refresh proxy switches you from one to the other. Let me lay out both so you can pick the one matching your goal.

Model 1 — connection JWT + client-side refresh (this is the one you're describing wanting)

• Client provides a JWT via getToken. Centrifugo verifies it itself (client.token.* config) and takes user + exp from it.
• Because Centrifugo knows the connection expires and the client owns the token, the connect reply contains expires: true with a ttl. The SDK arms a timer and calls your getToken again shortly before expiration, then sends a refresh command with the fresh token over the existing connection.
• No disconnect, no reconnect — exactly the behaviour you're after. Your current "expire then reconnect" workaround is not needed here.
• Requirements: the token must be verifiable by Centrifugo, and sub (user ID) must stay the same across refreshes, otherwise the connection is closed.
• Server-side subscriptions still work in this model: put them into the subs claim of the connection token (they are re-evaluated on every client-side refresh), or have your backend call the server API subscribe from the same endpoint that issues the token.

Model 2 — connect proxy + refresh proxy (server-side refresh)

• Client connects without a token; the connect proxy authenticates it and returns user, expire_at, optional info/meta/subs.
• When expire_at approaches, Centrifugo calls your refresh proxy. Your backend answers with a new expire_at and the connection is prolonged — again without any disconnect and without involving the client at all.
• In this model the connection lifetime is fully owned by your backend, so the refresh request intentionally carries no token — only client, user, transport, protocol, encoding and (if enabled) meta. The expectation is that the backend decides from its own session/state, not from a credential re-supplied by the browser. If the refresh handler needs context from connect time, attach it to meta in the connect proxy result — it's kept with the connection and passed back on refresh (and can be updated from a refresh reply).
• Because the server owns refresh here, Centrifugo sends expires: false in the connect reply, so the SDK never schedules a client-side refresh and never calls getToken again. That's why you observe what you observe.

A note on your current setup

The two models are not meant to be combined, and one detail is worth checking on your side: Centrifugo calls the connect proxy only when the client did not send a token. If a token is present in the connect command, Centrifugo verifies it with its own token verifier and the connect proxy is not invoked at all. The connect proxy request also has no token field. So if you both configure getToken and rely on a connect proxy, it's likely that only one of the two is actually taking effect — could you clarify how your connect proxy currently receives the JWT (connect data payload? a forwarded header?), and whether Centrifugo is configured to verify these tokens itself?

Recommendation

If your backend is the authority on the session, Model 2 alone already gives you refresh without reconnects — it just doesn't need a fresh browser-issued token to do it. If you specifically want the browser to keep supplying short-lived JWTs, then Model 1 is the right fit: drop the refresh proxy, let Centrifugo verify the tokens, and move server-side subscription setup into the subs claim or a server API call.

If neither maps cleanly onto your case, could you share a bit more detail — in particular, what the refresh proxy needs a freshly-issued client token for (is it re-authorizing against an upstream system, carrying updated claims/permissions, or something else?), and what your connect proxy does beyond establishing the server-side subscription? With that we can look at which of the existing mechanisms fits, or whether something is genuinely missing.

[vishveshyadav]

Hello @FZambia,

Thanks a million for going over the internals of Centrifugo.

My existing setup:
I am using client-side connect and subscriptions at the time of creating the Centrifugo client I just pass the getToken callback, then subscribe to the required Centrifugo channel via websocketCentrifugoClient.newSubscription(channelName) separately. As you rightly mentioned, refresh is handled by the SDK via calling the getToken callback again. The passed JWT is verified by Centrifugo by fetching our JWKS from an endpoint and verifying the iss/aud claims.

• In this case all our channels are user_limited_channels, so we are not passing any subscription token.
• We add a separate channel_subject: <tenant_id>.<user_uuid>, and configure Centrifugo to read that as user_uuid from the JWT.

What I am considering for another use case and what's different here:

• The process of issuing a Centrifugo-compatible JWT is complex, and I don't want every client to go through that.
• The channels are a mix of user_limited_channels and regular channels where more than one user can connect.
• This is real multi-tenancy: a channel is shared across many users, and we need to make sure no user from a different tenant can subscribe to it.

Because of this, I'm considering using backend proxies instead:

• Passing the client's Authorization header as an "emulated header" to the connect proxy, which resolves and verifies the user/tenant there.
• Using the subscription proxy (configured at the channel level) to verify tenant access. From the docs, it looks like this proxy is invoked with the user ID assigned during the connect proxy phase, plus the channel name being subscribed to.

For refresh, I want to avoid maintaining explicit session state in our backend. My plan, based on your response:

• The connect proxy resolves tenant_id/user_uuid once and returns it inside meta.
• Centrifugo holds onto that as part of the connection.
• The refresh proxy then reads the same meta on every refresh call and can make its live decision (e.g. re-checking revocation/tenant access against our backend using that identity) without needing the original Authorization header at all it's already stale by refresh time anyway. The refresh proxy can also return an updated meta, so subsequent refresh/subscribe calls see fresh data instead of the original connect-time snapshot.

Two questions to confirm I'm not misunderstanding anything:

1. Is meta the correct/idiomatic mechanism for carrying resolved identity state from connect through to subscription proxy and refresh proxy, or would you recommend a different pattern?
2. When the refresh proxy returns a new meta, does that fully replace the previously stored value, or merge with it? This affects whether I need to echo back unchanged fields on every refresh.

Does this overall design (connect proxy resolves tenant → stores in meta → subscription proxy + refresh proxy read from meta) look correct for a multi-tenant, no-client-JWT setup, or is there a gap I'm missing?