skip to content

With the Firebase Admin SDK, how do you cut off a stolen phone's session in a notes app, and why might its calls still succeed?

level: seniorimportance: should knowfreq 40%

answer

  1. stateless JWTs cannot be recalled
  2. revokeRefreshTokens stops the next refresh
  3. tokensValidAfterTime vs auth_time
  4. checkRevoked closes the hour

basics

~10 s

Call revokeRefreshTokens(uid) so no device can mint new ID tokens. ID tokens already issued stay valid for up to an hour, so endpoints that must refuse them at once verify with verifyIdToken(idToken, true).

solid answer

~40 s

`getAuth().revokeRefreshTokens(uid)` sets the user's `tokensValidAfterTime` to now, which kills every refresh token the user holds, on all devices, so each session dies at its next refresh. But Firebase ID tokens are stateless JWTs: one the thief's phone already holds still passes a plain `verifyIdToken` until its `exp`, up to an hour away. To close that window, verify with `verifyIdToken(idToken, true)`: the Admin SDK then looks up the user, rejects with `auth/user-disabled` if the account is disabled, and with `auth/id-token-revoked` if the token's `auth_time` is earlier than `tokensValidAfterTime`. That lookup costs a round trip to the Auth backend per call, so teams usually apply it to sensitive endpoints. If the account itself is compromised, also disable it with `updateUser(uid, { disabled: true })`.

code

typescript · 20 lines
typescript
import { getAuth } from "firebase-admin/auth";

// Support tool: the user reports a stolen phone.
export async function endAllSessions(uid: string): Promise<void> {
  await getAuth().revokeRefreshTokens(uid); // sets tokensValidAfterTime to now
}

// Sensitive endpoint: refuse tokens from revoked sessions or disabled users.
export async function uidForSensitiveCall(idToken: string): Promise<string | null> {
  try {
    const decoded = await getAuth().verifyIdToken(idToken, true); // one extra user lookup
    return decoded.uid;
  } catch (err) {
    const code = (err as { code?: string }).code;
    if (code === "auth/id-token-revoked" || code === "auth/user-disabled") {
      return null; // answer 401 so the app makes the user sign in again
    }
    throw err;
  }
}

go deeper

for a junior

Know that revokeRefreshTokens signs a user out everywhere at the next refresh, and that ID tokens are short-lived JWTs that cannot be recalled.

for a middle

Explain tokensValidAfterTime, the up-to-an-hour window it leaves, and what verifyIdToken(idToken, true) adds, including the user-disabled case.

for a senior

Choose which endpoints pay for the revocation lookup, know that the session's auth_time, not iat, is compared, and spot the emulator always checking revocation while production code forgot to.

for a principal

Set the organisation's exposure budget for a stolen token per endpoint class, and decide when support revokes, disables, or both, and who may trigger it.

## Why one call is not enough Firebase ID tokens are **stateless JWTs**: once issued, a token proves who the caller is until its `exp`, one hour after issue, and nothing can recall it from the phone that holds it. A session's real lifetime comes from the **refresh token**, which the SDK uses about once an hour to mint the next ID token. Cutting off a stolen phone therefore has two halves: stop new ID tokens from being minted, and stop the ones already out there from being accepted. ## Step 1: revoke the refresh tokens `getAuth().revokeRefreshTokens(uid)` revokes **all** of the user's refresh tokens, on every device and not only the stolen one. It works by setting the user's **`tokensValidAfterTime`** to the current time in whole seconds, taken from the clock of the server that makes the call, which is why the Admin SDK reference asks for a correctly synchronised clock. From then on: - no device can use its old refresh token to mint a new ID token, so each session dies at its next refresh; - the user's other devices are signed out as well and must sign in again; - an ID token **already issued** stays valid until it expires, up to an hour, as far as plain `verifyIdToken` is concerned. Firebase also revokes on its own after some events: a password reset revokes the user's existing tokens, and major account changes such as an email address update end the refresh tokens. ## Step 2: close the one-hour window To reject the already-issued tokens, verify with **`verifyIdToken(idToken, true)`**. With `checkRevoked` set, the Admin SDK verifies the token as usual, then fetches the user record and: 1. rejects with **`auth/user-disabled`** if the account is disabled; 2. rejects with **`auth/id-token-revoked`** if the token's **`auth_time`** is earlier than the user's `tokensValidAfterTime`; 3. otherwise returns the decoded token. The check is about sessions, not individual tokens. `auth_time` records when the user signed in to this session and is carried unchanged into every hourly refresh, so every token descended from a sign-in before the revocation is rejected, however recently it was refreshed. A genuine sign-in after the revocation gets a new `auth_time` and passes. ## The cost, and where to pay it `checkRevoked` adds a round trip to the Firebase Authentication backend on every call that uses it, where plain verification needs only cached public keys. Teams choose where to pay: | Endpoint | Typical choice | |---|---| | Low-risk reads (list my notes) | plain `verifyIdToken`; accept up to an hour of exposure | | Sensitive calls (export every note, change the account email) | `verifyIdToken(idToken, true)` | | Firestore or Storage reached directly from the app | Security Rules, which see revocation only if you store a revocation time for them to compare against | Firebase's documentation shows that last pattern for Realtime Database: the backend writes the revocation time to a path clients cannot write, and rules compare `auth.token.auth_time` with it. Writing those rules is a Security Rules subject. ## Disabling versus revoking For a stolen phone, revocation is usually enough: the real owner signs in again on their other devices and carries on. If the account itself is compromised, also **disable** it with `updateUser(uid, { disabled: true })`. A disabled user cannot sign in, its refresh tokens stop working, and `checkRevoked` reports `auth/user-disabled` for its outstanding ID tokens. Either way the Android client should treat the resulting 401 as "sign in again", not as a transient error to retry. ## A runbook for the stolen phone 1. Call `revokeRefreshTokens(uid)` and note the time it returns. 2. If the password or the identity-provider account may be compromised too, disable the user, or have the owner change the password, which itself revokes the old tokens. 3. Make sure every sensitive endpoint verifies with `checkRevoked`; for the next hour, those endpoints reject the thief's unexpired tokens while plain verification still accepts them. 4. If the app reads Firestore or Realtime Database directly, make sure the rules compare against a stored revocation time, or accept that direct reads keep working until the tokens expire. 5. Tell the owner to expect a sign-in prompt on every device. ## In the emulator When `FIREBASE_AUTH_EMULATOR_HOST` is set, the Admin SDK runs the disabled and revoked check on every `verifyIdToken`, whatever you pass. A test suite against the Auth emulator can therefore pass while production code that forgot `checkRevoked` keeps accepting a revoked token for up to an hour.

  • Why does revokeRefreshTokens care whether the calling server's clock is correct?
    The Admin SDK sets `tokensValidAfterTime` from the calling server's own clock, in seconds. If that clock runs fast, a user who signs in again right after the revocation can get an `auth_time` earlier than the stored value and be rejected as revoked; if it runs slow, tokens from sessions started just before the revocation can slip through the check.
  • How does the Android app find out that its Firebase session was revoked?
    Not instantly. At the next refresh the SDK's refresh token is rejected and the user is signed out, which an `AuthStateListener` sees as the current user going null. Sooner than that, your backend answers a `checkRevoked` failure with a 401, and the app should send the user to sign in or re-authenticate instead of retrying.
  • When is revoking the refresh tokens not enough, so you also disable the account?
    When the attacker can simply sign in again: a leaked password or a hijacked identity-provider account. Revocation ends existing sessions but does not stop a new sign-in; `updateUser(uid, { disabled: true })` blocks sign-in until you re-enable the user, and outstanding tokens fail `checkRevoked` with `auth/user-disabled`.

A festival that prints a new wristband for each guest every hour at the ticket desk. Cancelling a guest's ticket stops the desk printing them new wristbands, but the one on their wrist still opens every gate until it expires, unless a gate also checks the cancelled-tickets list, which costs a lookup at that gate.

  • revokeRefreshTokens immediately invalidates every ID token the phone already holds.
  • Plain verifyIdToken rejects revoked tokens, so no backend change is needed.
  • revokeRefreshTokens signs out only the device you name.
  • Run checkRevoked on every request; the extra lookup costs nothing.
  • Changing the user's password leaves existing sessions untouched.