skip to content

How does a backend verify a Firebase ID token with the Admin SDK's verifyIdToken, and what does that call not check?

level: middleimportance: must knowfreq 70%

answer

  1. never trust the decoded body alone
  2. signature, exp, aud, iss, sub
  3. aud is your project ID
  4. revocation needs checkRevoked

basics

~20 s

The Admin SDK's verifyIdToken checks the RS256 signature against Google's public keys, the expiry and issue times, and that aud and iss name your project, then returns the uid and claims. It skips revocation and disabled-user checks unless checkRevoked is true.

solid answer

~50 s

The app sends `getIdToken()`'s JWT as a bearer token over HTTPS, and the server calls `getAuth().verifyIdToken(idToken)`. The Admin SDK checks that the header is `RS256` with a `kid` matching one of Google's public keys for Firebase ID tokens, verifies the signature, checks that `exp` is in the future and `iat` and `auth_time` in the past, that `aud` is your project ID and `iss` is `https://securetoken.google.com/<projectId>`, and that `sub` is a non-empty uid. The keys are cached, so this needs no call to the Auth backend. What it does not tell you: whether the user was disabled or their refresh tokens revoked since the token was minted (pass `checkRevoked` = true for that, at the cost of a user lookup), and whether this user may do this action, which is your code. It also rejects custom tokens by design.

code

typescript · 14 lines
typescript
import { initializeApp } from "firebase-admin/app";
import { getAuth, DecodedIdToken } from "firebase-admin/auth";

initializeApp(); // project ID from the credentials or GOOGLE_CLOUD_PROJECT

export async function verifyCaller(authorization: string | undefined): Promise<DecodedIdToken> {
  const match = /^Bearer (.+)$/.exec(authorization ?? "");
  if (!match) {
    throw new Error("missing bearer token"); // answer 401
  }
  // Checks signature, exp, iat, aud, iss and sub against cached public keys.
  // It does not look up the user, so revocation and disabling go unnoticed here.
  return getAuth().verifyIdToken(match[1]);
}

go deeper

for a junior

Know that the app sends its ID token, not the uid, and that the server must verify it with the Admin SDK before reading the uid.

for a middle

List what verifyIdToken checks (signature, exp, iat, aud, iss, sub) and where the Admin SDK gets the project ID that aud must match.

for a senior

Explain the gaps: revoked or disabled users pass without checkRevoked, custom tokens are refused, and a wrong project ID rejects everything; decide where the extra lookup is worth paying.

for a principal

Set the team's default for which endpoints run the revocation check, and how roles flow from custom claims instead of request fields.

## Why the backend verifies a token, not a uid An Android app talks to Firestore and Cloud Storage through Firebase SDKs that check identity for you, but a backend of your own (a notes app's export service, say) must work out who is calling. The pattern: the client calls `getIdToken(false)`, sends the JWT in an `Authorization: Bearer` header over HTTPS, and the server **verifies the token** before trusting any field in it. Only then is `decoded.uid` the caller's identity. A callable Cloud Function performs this verification for you and hands the handler the caller's auth context; that path is covered with Cloud Functions. ## What verifyIdToken checks With the Admin SDK for Node.js, `getAuth().verifyIdToken(idToken)` resolves to a `DecodedIdToken` or rejects. It accepts a token only if it is well formed, unexpired and properly signed. Concretely: - the header's `alg` is `RS256` and its `kid` names one of Google's public keys for Firebase ID tokens, and the signature verifies with that key; - `exp` is in the future, and `iat` and `auth_time` are in the past; - `aud` equals **your Firebase project ID**, and `iss` is `https://securetoken.google.com/<projectId>` for the same project; - `sub` is a non-empty string; it becomes `uid`. The public keys come from a Google endpoint and are cached for as long as the response's `Cache-Control` `max-age` allows, so routine verification makes no call to the Firebase Authentication backend. On failure the promise rejects with a `FirebaseAuthError`; an expired token gives `auth/id-token-expired`, which the client answers by fetching a fresh token and retrying. ## Where the project ID comes from The `aud` check needs a project ID, and a backend that resolves the wrong one rejects every token with an "incorrect aud" error. The Admin SDK uses the first one it finds of: 1. the `projectId` option passed to `initializeApp`; 2. the `project_id` field of the service account credentials; 3. the `GOOGLE_CLOUD_PROJECT` environment variable, set for code on Google infrastructure; and, failing those, it can discover the project from application default credentials. A staging backend initialised with another project's service account is the classic way to trip this. ## What the decoded token gives you The `DecodedIdToken` is the only source of identity the handler should use: - `uid`, the user's Firebase ID (the same value as `sub`); - `email` and `email_verified`, when the account has an email; - `firebase.sign_in_provider`, such as `password`, `google.com`, `anonymous` or `custom`, and `firebase.identities`, the identities linked to the account; - `auth_time`, when the user signed in to this session, which revocation checks compare; - any **custom claims**, as top-level keys, so a `premium` claim is read as `decoded.premium`. Anything the request body says about who the caller is or what role they hold should be ignored in favour of these fields. ## What it does not check | Question | Answered by plain `verifyIdToken`? | How to get it | |---|---|---| | Did Firebase issue this token for my project, and is it unexpired? | yes | (built in) | | Has the user been disabled since the token was issued? | no | `verifyIdToken(idToken, true)` | | Were the user's refresh tokens revoked? | no | `verifyIdToken(idToken, true)` | | May this user perform this action? | no | your code, often reading custom claims from the token | `checkRevoked` adds a lookup of the user record in the Auth backend, so it costs a network round trip on every call that uses it. Without it, a disabled user's existing ID token keeps verifying until it expires, up to an hour. ## Tokens it refuses on purpose `verifyIdToken` is meant for **ID tokens minted by the client SDKs**. A token from `createCustomToken` is a different JWT, signed by your service account and addressed to the Identity Toolkit API, and verification rejects it with a message saying it expected an ID token but was given a custom token. A custom token is something the client exchanges with `signInWithCustomToken`, never a bearer token for your API. ## Without the Admin SDK If the backend's language has no Admin SDK, a standard JWT library can apply the same rules: the header and payload checks above, and the signature checked against the public keys published at Google's `[email protected]` x509 endpoint, re-fetched according to `max-age`. Decoding the payload without checking the signature is not verification: anyone can write a JWT body that says any `uid`.

  • Your backend runs in a staging Firebase project while the Android app signs users in to production. What fails, and why?
    Every `verifyIdToken` call rejects, because the tokens' `aud` and `iss` name the production project ID while the Admin SDK resolved staging's from its options, credentials or environment. Either point the app at the staging project or initialise the backend with the production project; one backend cannot silently accept another project's tokens.
  • Should the backend trust a role the Android app sends next to the Firebase ID token?
    No. Only claims inside a token the backend verified are trustworthy; a field in the request body is whatever the caller typed. Put roles in custom claims set by the Admin SDK, then read them from the `DecodedIdToken` that `verifyIdToken` returns.
  • How does the Admin SDK behave when you test verifyIdToken against the Firebase Auth emulator?
    With `FIREBASE_AUTH_EMULATOR_HOST` set, the Admin SDK accepts the emulator's tokens, which carry no production signature, and it always runs the disabled and revoked checks, whatever you pass for `checkRevoked`. A test can therefore pass while production code that never asked for the revocation check lets a revoked token through.

  • Base64-decode the JWT and read sub; that is enough to know the caller.
  • verifyIdToken also rejects tokens of users who were disabled after sign-in.
  • Any token Google signed is fine, whichever Firebase project issued it.
  • A custom token from createCustomToken can be checked with verifyIdToken too.
  • Trust the role field the app sends alongside the token.