Understanding Authentication Tokens with Firebase Auth

Note: This article is a personal study note from when I was researching Firebase Auth tokens. It’s more of a compilation of what I learned during the process rather than a comprehensive guide.

This guide covers the fundamentals of authentication tokens in OAuth 2.0 / OpenID Connect, with a focus on Firebase Auth’s unique characteristics.

---

• Authentication comes first, then authorization. An unauthenticated user cannot be authorized.

---

• Purpose: Prove “who this person is”
• Usage: Consumed within the client (frontend)
• Use cases: Display username, show profile, personalize UI
• Format: JWT (JSON Web Token)

• Purpose: Prove “authorization to access this resource”
• Usage: Sent to backend API (Authorization: Bearer {token})
• Use cases: API authorization, resource access control
• Format: JWT or Opaque Token

• Purpose: Obtain new ID Token / Access Token
• Usage: Token refresh requests to the auth server
• Use cases: Get new tokens when Access Token expires, without re-login
• Format: Opaque Token (contents not visible)

---

ID Tokens and Access Tokens are often created in JWT format. A JWT consists of three parts:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL...
├──────────── Header ────────────┤├────────── Payload ──────────...

{
  "alg": "RS256",
  "typ": "JWT"
}

• alg: Signature algorithm
• typ: Token type

{
  "iss": "https://securetoken.google.com/my-project",
  "sub": "XeOK4KBxyz123abc",
  "aud": "my-project",
  "iat": 1704067200,
  "exp": 1704070800,
  "email": "user@example.com",
  "firebase": {
    "sign_in_provider": "password"
  }
}

• Header and Payload are signed with a private key
• If tampered with, the signature won’t match
• Server-side verification via verifyIdToken() etc.

---

Upon successful authentication, ID Token / Access Token / Refresh Token are issued simultaneously in a single response:

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyB...",
  "id_token": "eyJhbGci..."
}

• Auth server decides: The auth server (IdP) sets all token validity periods
• For JWTs: The exp claim contains the expiration timestamp
• Configurability: Varies by provider - some allow developer configuration, others don’t

• When Access Token expires, use Refresh Token to get new tokens
• A single Refresh Token refreshes both ID Token and Access Token
• User doesn’t need to re-login

---

• In Firebase, ID Token handles both “authentication” and “authorization”
• Simpler for developers - only one token type to manage

Firebase Refresh Token is invalidated only when:

• User is deleted
• User is disabled
• Password or email address is changed
• revokeRefreshTokens(uid) is explicitly called

• Just call user.getIdToken() - automatically refreshes when expired
• Developers don’t need to handle Refresh Token directly

• Cannot directly access Refresh Token
• Can only invalidate via revokeRefreshTokens(uid)

Why this design?

Firebase Auth achieves “security-wise tokens change every hour, but UX-wise the user stays logged in”.

---

Where to store tokens and session information involves security vs. convenience trade-offs.

• Storage location: Browser (Web Storage API)
• Lifetime: Until tab/window closes
• Scope: Same tab only (not shared across tabs)
• Use cases: Temporary data (UI state needed only while logged in)

// Store
sessionStorage.setItem('key', 'value');
// Retrieve
const value = sessionStorage.getItem('key');
// Delete
sessionStorage.removeItem('key');

• Storage location: Browser (Web Storage API)
• Lifetime: Persistent until explicitly deleted
• Scope: Shared within same origin (across all tabs)
• Use cases: User settings, cache data

// Store
localStorage.setItem('key', 'value');
// Retrieve
const value = localStorage.getItem('key');
// Delete
localStorage.removeItem('key');

• Storage location: Browser
• Lifetime: Set via maxAge/expires
• Scope: Same origin (subdomains configurable)
• Key feature: Automatically sent to server with requests
• Use cases: Auth tokens, session management

// Set (server-side)
response.cookies.set('name', 'value', {
  httpOnly: true,  // JS cannot access
  secure: true,    // HTTPS only
  sameSite: 'lax', // CSRF protection
  maxAge: 86400,   // 1 day (seconds)
});

• Storage location: Browser (NoSQL database)
• Lifetime: Persistent until explicitly deleted
• Scope: Within same origin
• Use cases: Large data, offline data, Firebase SDK token storage

Firebase Auth SDK automatically stores ID Token and Refresh Token in IndexedDB:

IndexedDB: firebaseLocalStorageDb
  └─ firebaseLocalStorage
      └─ firebase:authUser:{apiKey}:{appName}

These have similar names but completely different mechanisms:

---

Cookies are classified into 2 types based on expiration settings:

In Firebase Auth documentation, “Session Cookie” has a different meaning from the general definition:

In other words, Firebase’s “Session Cookie” is technically a Persistent Cookie.

Firebase Auth Session Cookie is a mechanism for managing user sessions server-side. Send ID Token to server, convert it to Session Cookie, then use Cookie-based auth for subsequent requests.

// Server-side: Receive ID Token and issue Session Cookie
const expiresIn = 60 * 60 * 24 * 1000; // 1 day (milliseconds)

// Verify ID Token and create Session Cookie
const sessionCookie = await adminAuth.createSessionCookie(idToken, { expiresIn });

// Set Cookie in response
response.cookies.set('__session', sessionCookie, {
  httpOnly: true,    // JavaScript cannot access (XSS protection)
  secure: true,      // HTTPS only
  sameSite: 'lax',   // CSRF protection
  maxAge: expiresIn / 1000,
  path: '/',
});

// Server-side: Verify Session Cookie
const sessionCookie = cookies().get('__session')?.value;
const decodedClaims = await adminAuth.verifySessionCookie(sessionCookie, true);
// Access decodedClaims.uid, decodedClaims.email, etc.

XSS Attack Resistance

CSRF Attack Resistance

Token Leakage Impact

Decision Points

Reference Documentation:

• OWASP - Cross-Site Scripting (XSS)
• OWASP - Cross-Site Request Forgery (CSRF)

Instead of using Session Cookie, send ID Token directly to API. Leverages Firebase SDK’s auto-refresh feature.

Characteristics:

API Call Example:

// Client-side
const user = auth.currentUser;
const idToken = await user.getIdToken(); // Auto-refresh if near expiration

const response = await fetch('/api/data', {
  headers: {
    'Authorization': `Bearer ${idToken}`,
  },
});

Server-side Verification:

// API Route
const authHeader = request.headers.get('Authorization');
const idToken = authHeader?.split('Bearer ')[1];

const decodedClaims = await adminAuth.verifyIdToken(idToken);
// Access decodedClaims.uid, decodedClaims.email, etc.

Changes When Migrating from Session Cookie:

---

---

---

• Firebase Auth - Manage User Sessions
• Firebase Auth - Manage Session Cookies
• Firebase Auth - Verify ID Tokens
• OAuth 2.0 RFC 6749
• OpenID Connect Core 1.0