Cross-App SSO with JWT & Refresh-Token Rotation Done Right

The architecture has four pieces that have to work together: one JWT issuer for the whole suite, public-key distribution via JWKS, short-lived access tokens with per-app audience claims, and refresh tokens that rotate on every use with reuse detection. Drop any piece and you get a different system with weaker guarantees.

Single JWT issuer for the suite

Start with the issuer. Pick one — Supabase Auth, Auth0, Clerk, AWS Cognito, or a service you own — and make it the sole authority that mints tokens for the suite. Every app in the suite trusts the same issuer and nothing else. The issuer is responsible for one thing: turning a verified credential (email + password, OAuth code, magic link, passkey) into a signed JWT carrying the user's identity, tenant scope, and roles. It is also the only place that holds refresh tokens, the only place that can revoke a session, and the only place that knows the full set of apps a user is signed in to.

JWTs are emitted with at minimum these claims:

type AccessTokenClaims = {
  iss: "https://auth.example.com";   // shared issuer URL
  sub: string;                        // stable user id
  aud: string;                        // per-app audience: 'admin-app' | 'customer-app' | ...
  exp: number;                        // NumericDate, ~5-15 minutes from now
  iat: number;                        // issued at
  jti: string;                        // unique token id, used for denylist if you need instant revocation

  // App-readable scope — pulled from immutable app metadata, not user metadata
  tenant_id: string;
  roles: string[];
};

Per-app audience claims

RFC 7519 specifies that the audience claim identifies the recipients the JWT is intended for, and that recipients that do not identify themselves with a value in the audience claim when the claim is present must reject the JWT. Use that mechanism literally: mint tokens with aud: 'admin-app' for admin sign-in and aud: 'customer-app' for customer sign-in, so a token captured from one app cannot be replayed against another even though both verify the same issuer. The audience is enforced at verify time:

import { jwtVerify, createRemoteJWKSet } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://auth.example.com/.well-known/jwks.json"));

export async function verifyAccessToken(
  token: string,
  expectedAudience: string,
): Promise<AccessTokenClaims> {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: "https://auth.example.com",
    audience: expectedAudience,
    // jose enforces 'exp' automatically; clockTolerance covers small drift.
    clockTolerance: 30,
  });
  return payload as AccessTokenClaims;
}

JWKS-based key distribution

Public-key distribution is what makes the verifier portable. The issuer publishes a JWKS endpoint — a URL that returns the current set of public keys in JSON Web Key format. Each app fetches the JWKS at startup, caches it in memory, and refreshes when it sees a token signed with a kid it does not recognize. This is how you rotate signing keys without deploying every app: mint with a new kid, the JWKS endpoint returns both keys for a transition window, every app's verifier picks up the new key the first time it sees it, and once no tokens with the old kid are in flight, the old key is removed. The createRemoteJWKSet helper in jose handles fetch, cache, and refresh automatically. Hardcoding the public key works for one app and breaks the moment a key has to rotate, which is something you want to be able to do on five minutes' notice if a key ever leaks.

Short-lived access tokens

Access tokens are short — 5 to 15 minutes — for two reasons. First, propagation: when a user signs out or a role changes, every app's view of that user is stale until its current access token expires, so shorter TTL means shorter staleness. Second, blast radius: an access token captured from a log file, a server-side request, or a leaky URL is usable for at most its TTL. Short tokens are not free — they mean more refresh traffic to the issuer — but they are the right default unless you have a specific reason to lengthen them.

Rotating refresh tokens with reuse detection

Refresh tokens are long — 7 to 30 days — because they are how the user stays signed in across visits. They are also the high-value target. RFC 6749 defines refresh tokens as credentials intended for use only with authorization servers, not sent to resource servers, which is the property that makes the security model work: the refresh token only ever travels between the client and the issuer, and the issuer is the only place it can be exchanged. Apps in the suite do not see a refresh token at all — they receive an access token from the client on each request and verify it against the JWKS.

Rotation is the security mechanism that makes long-lived refresh tokens safe. Every time the client exchanges a refresh token for a new access token, the issuer returns a new refresh token alongside it, marks the old one as used, and refuses to honor the old one a second time. Supabase Auth implements this as single-use refresh tokens — a refresh token can only be used once — with a 10-second reuse window for race conditions where the network blips and the client legitimately retries with the same token. Outside that window, reusing a token means one of two things: an attacker stole it and used it before the real user could refresh, or the real user is on a slow connection and just took the loss. The auth provider cannot tell which, so it takes the safe action and revokes the entire session. Supabase's documentation describes this exactly: "the whole session is regarded as terminated and all refresh tokens belonging to it are marked as revoked."

Auth0 calls the same mechanism token-family invalidation: the original refresh token and every token that descends from it are killed at once, and every subsequent request is denied until the user re-authenticates. The implementation detail is the same and the security property is the same — a stolen refresh token works exactly once and surfaces itself the moment the real user tries to refresh.

Client-side coalesced refresh

The client-side refresh flow looks like this:

import jwt from "jsonwebtoken";

// Pseudocode for an SDK that wraps the auth provider's refresh endpoint.
// In practice you use the provider's SDK; the contract is the same.
type TokenPair = { access_token: string; refresh_token: string; expires_in: number };

let current: TokenPair | null = loadFromSecureStorage();
let refreshInFlight: Promise<TokenPair> | null = null;

export async function getAccessToken(): Promise<string> {
  if (!current) throw new Error("not signed in");

  const decoded = jwt.decode(current.access_token) as { exp: number };
  const msUntilExp = decoded.exp * 1000 - Date.now();

  // Refresh proactively at 30 seconds before expiry so the next request
  // does not race an expiring token.
  if (msUntilExp > 30_000) return current.access_token;

  // Coalesce concurrent refresh calls — every caller waits on the same
  // in-flight refresh instead of firing N parallel exchanges that would
  // trip reuse detection.
  refreshInFlight ??= rotateRefreshToken(current.refresh_token).finally(() => {
    refreshInFlight = null;
  });

  current = await refreshInFlight;
  saveToSecureStorage(current);
  return current.access_token;
}

async function rotateRefreshToken(refreshToken: string): Promise<TokenPair> {
  const res = await fetch("https://auth.example.com/token", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ grant_type: "refresh_token", refresh_token: refreshToken }),
  });
  if (!res.ok) {
    // 401 here usually means the session was revoked — either the user
    // signed out from another app or reuse detection fired. Either way,
    // the client should drop local state and route the user to sign-in.
    clearSecureStorage();
    throw new Error("session revoked, re-authentication required");
  }
  return res.json();
}

Coalescing concurrent refresh calls is the part most implementations get wrong on the first pass. If two tabs of the same app both notice the access token is about to expire and both fire a refresh with the same refresh token, the first call rotates and the second call hits reuse detection — even though both came from the same legitimate user. The fix is the in-flight promise above: every caller within the same process waits on the same refresh, and only one network call actually rotates. The 10-second reuse window catches the cross-tab case where two separate processes do the same thing.

Sign-out propagation

Sign-out is the other piece most teams underspecify. The user clicks sign-out in any app. That app calls the issuer's revoke endpoint with the current refresh token. The issuer marks the refresh token as revoked. Every app in the suite keeps working until its current access token expires — at most 15 minutes — at which point the refresh call returns 401 and the user is sent to sign in again. Propagation latency equals the access-token TTL, which is the price of not running a denylist check on every request. If you need instant propagation — for compliance, for an admin "force sign-out" feature, or for high-stakes flows like fund transfers — add a revocation check on the jti claim against a Redis denylist. The cost is one Redis hit per request; the gain is sub-second sign-out across every app. Most suites do not need this for normal sign-out and do need it for the admin "force sign-out this user everywhere right now" button.

The "user logs out everywhere" requirement is the test for whether the architecture is right. With this pattern, the answer is: revoke the refresh token at the issuer, every app's session expires at the next refresh, done. Without this pattern — with per-app session storage, with separate auth per app, with the shared-cookie hack — the answer is some combination of "we cannot," "we have to clear cookies on each domain," and "the user has to sign out from each app manually." The first answer is what enterprise customers ask for in their security review. The other answers lose the deal.