Firebase Auth ↔ Flutter Secure Storage: Interoperability of Token Refresh and Revocation

Detecting Expiry

Firebase ID tokens are short‑lived JWTs (≈1 hour). The firebase_auth SDK does not fire a dedicated “expired” event. The most reliable client‑side approach is to call FirebaseAuth.instance.currentUser!.getIdTokenResult() before each protected request. The returned IdTokenResult contains expirationTime, issuedAtTime, and authTime. A simple helper can compare expirationTime to the local clock with a small skew (e.g. 60 s) and decide whether to force a refresh.

Future _ensureFreshToken() async {
  final user = FirebaseAuth.instance.currentUser;
  if (user == null) throw Exception('Not signed in');
  final result = await user.getIdTokenResult();
  final now = DateTime.now().toUtc();
  if (now.isAfter(result.expirationTime!.subtract(const Duration(seconds: 60)))) {
    // Token is about to expire – refresh it.
    return await user.getIdToken(true);
  }
  return result.token!;
}

Because flutter_secure_storage merely persists the refresh token, it cannot detect expiry. Treat the token stored there as a static key; only read it once at app start and keep it in memory. Do not store the ID token in secure storage unless you have a very specific use case (e.g. a native module that cannot use the Flutter SDK).

Revocation Strategy

Calling a custom revocation endpoint from the client on every request is unnecessary and fragile. Revocation is a server‑side concept: the Firebase Admin SDK verifies the auth_time against the account’s validSince value. Your backend should perform this check on every protected call using checkRevoked: true.

const decoded = await admin.auth().verifyIdToken(idToken, /* checkRevoked */ true);

If the token was revoked, the Admin SDK throws an auth/id-token-revoked error. The client should interpret a 401 with this error code as a sign that the refresh token is no longer valid, log the user out, and clear the stored refresh token.

Preventing Race Conditions

Concurrent API calls can trigger multiple refreshes if each one independently calls getIdToken(true). Use a “single‑flight” pattern: keep a single in‑flight Future that represents the current refresh operation. All callers await that future instead of starting a new one.

class AuthTokenProvider {
  Future? _refreshInFlight;
  final _lock = Object();

  Future token() async {
    final user = FirebaseAuth.instance.currentUser;
    if (user == null) throw Exception('Not signed in');
    final result = await user.getIdTokenResult();
    final now = DateTime.now().toUtc();
    if (now.isBefore(result.expirationTime!.subtract(const Duration(seconds: 60)))) {
      return result.token!;
    }
    return _withLock(() async {
      if (_refreshInFlight != null) return await _refreshInFlight!;
      _refreshInFlight = user.getIdToken(true);
      try {
        return await _refreshInFlight!;
      } finally {
        _refreshInFlight = null;
      }
    });
  }
}

When a request receives a 401 with an error code indicating token expiry or revocation, force a refresh once with getIdToken(true) and retry the request a single time. This guarantees that only one network call refreshes the token even under heavy concurrency.

Practical Checklist

• Pin firebase_auth and flutter_secure_storage to a stable version and test upgrade paths.
• Read the refresh token from secure storage only once at startup; keep it in memory for the session.
• Use getIdTokenResult() to decide when to refresh; do not store ID tokens in secure storage.
• Implement a single‑flight refresh wrapper to serialize concurrent refreshes.
• Let the backend enforce revocation with checkRevoked:true; treat a 401 from the server as a sign to log out.
• Optionally, expose a diagnostic flag that logs the token’s exp and local clock difference to aid debugging.

With these patterns, the app uses only valid, least‑privileged tokens, avoids stale claims, and eliminates race‑condition hazards without the overhead of per‑request revocation checks.