Part 4: Tokens and Token Management

The Token That Broke Production

Three months into my first major project, our API starting timing out. Users couldn't log in. After hours of panic debugging, I discovered the issue: every token validation was making a network call to MS Entra to fetch the JWKS. Under load, this choked our system.

The fix? Cache the JWKS. It took 10 minutes to implement and saved us thousands in infrastructure costs. Understanding tokens isn't optional—it's essential.

The Three Token Types

MS Entra issues three types of tokens, each serving a different purpose:

1. Access Tokens

Purpose: Call APIs Lifetime: Short (typically 1 hour) Format: JWT (JSON Web Token) Opacity: Treat as opaque (don't decode unless you're validating)

// Access token example (decoded for illustration)
{
  "aud": "api://payment-api",              // Audience: who can use this token
  "iss": "https://login.microsoftonline.com/{tenant}/v2.0",  // Issuer
  "iat": 1708185600,                        // Issued at
  "nbf": 1708185600,                        // Not before
  "exp": 1708189200,                        // Expires (1 hour later)
  "sub": "user-object-id",                  // Subject: user ID
  "oid": "user-object-id",                  // Object ID (same as sub in v2)
  "preferred_username": "[email protected]",
  "scp": "Payments.Read Payments.Write",    // Scopes granted
  "appid": "frontend-client-id",            // Application that requested token
  "ver": "2.0"                              // Token version
}

2. ID Tokens

Purpose: Identify the user Lifetime: Short (1 hour) Format: JWT Use: Client-side, for showing user info

// ID token example
{
  "aud": "frontend-client-id",              // Your app's client ID
  "iss": "https://login.microsoftonline.com/{tenant}/v2.0",
  "iat": 1708185600,
  "nbf": 1708185600,
  "exp": 1708189200,
  "name": "John Doe",                       // User's full name
  "preferred_username": "[email protected]",
  "oid": "user-object-id",                  // Unique user ID
  "sub": "user-subject-id",                 // Subject identifier
  "email": "[email protected]",
  "tid": "tenant-id",                       // Tenant ID
  "ver": "2.0"
}

3. Refresh Tokens

Purpose: Get new access tokens without user interaction Lifetime: Long (typically 90 days, can be revoked) Format: Opaque random string (not JWT) Security: Store securely, never log

// Refresh token (you never decode this)
"0.ARoA_abcdefghijklmnopqrstuvwxyz1234567890..."

// It's opaque - only MS Entra understands it

JWT Structure Deep Dive

JWTs have three parts separated by dots:

eyJ0eXAiOiJKV1QiLCJhbGc.eyJhdWQiOiJhcGk6Ly9wYXl.SflKxwRJSMeKKF2QT
     Header            .      Payload      .   Signature

Header

// Base64URL decoded
{
  "typ": "JWT",                // Token type
  "alg": "RS256",              // Signing algorithm (RSA with SHA-256)
  "kid": "key-id-12345"        // Key ID to find the public key in JWKS
}

The kid (key ID) is crucial—it tells you which public key to use for verification.

Payload (Claims)

// Base64URL decoded
{
  // Standard claims (defined by JWT spec)
  "iss": "https://login.microsoftonline.com/{tenant}/v2.0",  // Issuer
  "sub": "user-object-id",                                    // Subject
  "aud": "api://payment-api",                                 // Audience
  "exp": 1708189200,                                          // Expiration
  "nbf": 1708185600,                                          // Not before
  "iat": 1708185600,                                          // Issued at
  "jti": "unique-token-id",                                   // JWT ID
  
  // MS Entra-specific claims
  "oid": "user-object-id",                                    // Object ID
  "tid": "tenant-id",                                         // Tenant ID
  "preferred_username": "[email protected]",
  "name": "John Doe",
  "scp": "Payments.Read Payments.Write",                      // Scopes (delegated)
  "roles": ["Admin", "Finance"],                             // App roles
  "app_di": "frontend-client-id",                            // Application ID
  "appid": "frontend-client-id",                             // Same
  "azp": "frontend-client-id",                               // Authorized party
  "ver": "2.0"                                                // Token version
}

Signature

// Signature verification (conceptual)
const header = base64URLencode(headerJSON);
const payload = base64URLencode(payloadJSON);
const data = `${header}.${payload}`;

// MS Entra signs with private key
const signature = RSA_SHA256(data, privateKey);

// You verify with public key (from JWKS)
const isValid = RSA_SHA256_Verify(data, signature, publicKey);

Token Validation

Critical: Always validate tokens. Never trust decoded data without verification.

Validation Checklist

interface TokenValidation {
  signature: boolean;      // ✅ Verify cryptographic signature
  issuer: boolean;         // ✅ Check iss claim
  audience: boolean        // ✅ Check aud claim
  expiration: boolean;     // ✅ Check exp claim
  notBefore: boolean;      // ✅ Check nbf claim
  algorithm: boolean;      // ✅ Verify alg is allowed
}

Manual Validation Example

import jwt, { JwtPayload } from "jsonwebtoken";
import jwksClient from "jwks-rsa";

interface EntraToken extends JwtPayload {
  oid: string;
  preferred_username: string;
  scp?: string;
  roles?: string[];
}

class TokenValidator {
  private jwksClient: jwksClient.JwksClient;
  private tenantId: string;
  private clientId: string;
  
  constructor(tenantId: string, clientId: string) {
    this.tenantId = tenantId;
    this.clientId = clientId;
    
    // Create JWKS client (with caching!)
    this.jwksClient = jwksClient({
      jwksUri: `https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`,
      cache: true,              // ✅ Cache keys
      cacheMaxAge: 86400000,    // ✅ 24 hours
      rateLimit: true,          // ✅ Rate limit JWKS fetches
      jwksRequestsPerMinute: 10
    });
  }
  
  private async getSigningKey(kid: string): Promise<string> {
    const key = await this.jwksClient.getSigningKey(kid);
    return key.getPublicKey();
  }
  
  async validateToken(token: string): Promise<EntraToken> {
    // Step 1: Decode header to get kid
    const decoded = jwt.decode(token, { complete: true });
    
    if (!decoded || !decoded.header.kid) {
      throw new Error("Invalid token: missing kid");
    }
    
    // Step 2: Get public key from JWKS
    const publicKey = await this.getSigningKey(decoded.header.kid);
    
    // Step 3: Verify and validate
    try {
      const verified = jwt.verify(token, publicKey, {
        algorithms: ["RS256"],                    // Only allow RS256
        audience: this.clientId,                  // Must match your app
        issuer: `https://login.microsoftonline.com/${this.tenantId}/v2.0`,
        clockTolerance: 60                        // Allow 60s clock skew
      }) as EntraToken;
      
      return verified;
      
    } catch (error) {
      if (error instanceof jwt.TokenExpiredError) {
        throw new Error("Token expired");
      }
      if (error instanceof jwt.JsonWebTokenError) {
        throw new Error(`Token invalid: ${error.message}`);
      }
      throw error;
    }
  }
  
  validateScopes(token: EntraToken, requiredScopes: string[]): boolean {
    const tokenScopes = token.scp?.split(" ") || [];
    return requiredScopes.every(scope => tokenScopes.includes(scope));
  }
  
  validateRoles(token: EntraToken, requiredRoles: string[]): boolean {
    const tokenRoles = token.roles || [];
    return requiredRoles.some(role => tokenRoles.includes(role));
  }
}

// Usage in API
import express from "express";

const app = express();
const validator = new TokenValidator(
  process.env.AZURE_TENANT_ID!,
  process.env.AZURE_CLIENT_ID!
);

// Middleware
async function authenticateToken(req: express.Request, res: express.Response, next: express.NextFunction) {
  const authHeader = req.headers.authorization;
  const token = authHeader?.replace("Bearer ", "");
  
  if (!token) {
    return res.status(401).json({ error: "No token provided" });
  }
  
  try {
    const claims = await validator.validateToken(token);
    
    // Attach claims to request
    req.user = {
      id: claims.oid,
      email: claims.preferred_username,
      scopes: claims.scp?.split(" ") || [],
      roles: claims.roles || []
    };
    
    next();
  } catch (error) {
    return res.status(401).json({ error: "Invalid token" });
  }
}

// Protected endpoint
app.get("/api/payments", authenticateToken, async (req, res) => {
  // Token is validated, user info in req.user
  const payments = await getPayments(req.user.id);
  res.json(payments);
});

// Scope-protected endpoint
app.post("/api/payments", authenticateToken, async (req, res) => {
  const token = req.user;  // From middleware
  
  if (!validator.validateScopes(token, ["Payments.Write"])) {
    return res.status(403).json({ error: "Insufficient permissions" });
  }
  
  // Create payment...
  res.json({ success: true });
});

Using Microsoft Libraries

Instead of manual validation, use official libraries:

// Using @azure/msal-node (recommended)
import { ConfidentialClientApplication } from "@azure/msal-node";
import express from "express";

const msalConfig = {
  auth: {
    clientId: process.env.AZURE_CLIENT_ID!,
    authority: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}`,
    clientSecret: process.env.AZURE_CLIENT_SECRET!
  }
};

const cca = new ConfidentialClientApplication(msalConfig);

app.use(async (req, res, next) => {
  const token = req.headers.authorization?.replace("Bearer ", "");
  
  if (!token) {
    return res.status(401).json({ error: "No token" });
  }
  
  try {
    // Validate token
    const result = await cca.acquireTokenOnBehalfOf({
      oboAssertion: token,
      scopes: ["https://graph.microsoft.com/.default"]
    });
    
    // Token is valid if OBO succeeds
    req.user = result.account;
    next();
  } catch (error) {
    res.status(401).json({ error: "Invalid token" });
  }
});

JWKS (JSON Web Key Set)

JWKS is where MS Entra publishes its public keys for token verification.

JWKS Endpoint

https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys

JWKS Response

{
  "keys": [
    {
      "kty": "RSA",                                    // Key type
      "use": "sig",                                    // Usage: signature
      "kid": "key-id-12345",                          // Key ID
      "x5t": "thumbprint",                            // X.509 thumbprint
      "n": "modulus...",                              // RSA modulus
      "e": "AQAB",                                    // RSA exponent
      "x5c": ["certificate..."],                      // X.509 certificate chain
      "issuer": "https://login.microsoftonline.com/{tenant}/v2.0"
    },
    {
      // Additional keys for rotation
    }
  ]
}

Caching JWKS

Problem: Fetching JWKS on every request kills performance

Solution: Cache aggressively

import NodeCache from "node-cache";
import axios from "axios";

class JWKSCache {
  private cache: NodeCache;
  private jwksUri: string;
  
  constructor(tenantId: string) {
    this.jwksUri = `https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`;
    
    // Cache for 24 hours with automatic refresh
    this.cache = new NodeCache({
      stdTTL: 86400,           // 24 hours
      checkperiod: 3600,       // Check every hour
      useClones: false         // Better performance
    });
  }
  
  async getKey(kid: string): Promise<any> {
    // Try cache first
    let keys = this.cache.get<any[]>("jwks");
    
    if (!keys) {
      // Fetch from MS Entra
      const response = await axios.get(this.jwksUri);
      keys = response.data.keys;
      
      // Cache the keys
      this.cache.set("jwks", keys);
    }
    
    // Find key with matching kid
    const key = keys.find(k => k.kid === kid);
    
    if (!key) {
      // Key not found - might be rotated
      // Force refresh and try again
      this.cache.del("jwks");
      const response = await axios.get(this.jwksUri);
      keys = response.data.keys;
      this.cache.set("jwks", keys);
      
      return keys.find(k => k.kid === kid);
    }
    
    return key;
  }
}

Key Rotation

MS Entra rotates signing keys periodically (usually every 6 weeks).

What this means:

• JWKS contains multiple keys

• Old tokens signed with old keys remain valid

• Always fetch current JWKS if kid not found

Handling rotation:

async function verifyTokenWithRotation(token: string) {
  const decoded = jwt.decode(token, { complete: true });
  
  try {
    // Try with cached key
    const key = await jwksCache.getKey(decoded.header.kid);
    const publicKey = convertJWKtoP EM(key);
    return jwt.verify(token, publicKey);
    
  } catch (error) {
    if (error instanceof jwt.JsonWebTokenError) {
      // Key might be rotated - clear cache and retry
      jwksCache.clear();
      const key = await jwksCache.getKey(decoded.header.kid);
      const publicKey = convertJWKtoPEM(key);
      return jwt.verify(token, publicKey);
    }
    throw error;
  }
}

Token Lifetimes

Understanding and managing token lifetimes is critical.

Default Lifetimes

interface TokenLifetimes {
  accessToken: "1 hour";
  idToken: "1 hour";
  refreshToken: "90 days (rolling)";  // Extends with use
}

Configuring Lifetimes

Azure Portal → Entra ID → App registrations → Token configuration

Access token lifetime: 1 hour (default, can't extend)
ID token lifetime: 1 hour (default, can't extend)
Refresh token lifetime: Configurable via token lifetime policies

Token Lifetime Policies (PowerShell)

# Create custom token lifetime policy
New-AzureADPolicy -Definition @("{`"TokenLifetimePolicy`":{`"Version`":1,`"AccessTokenLifetime`":`"02:00:00`"}}") -DisplayName "CustomTokenLifetime" -Type "TokenLifetimePolicy"

# Apply to service principal
Add-AzureADServicePrincipalPolicy -Id <ServicePrincipalId> -RefId <PolicyId>

Refresh Token Behavior

// Frontend: Acquire token silently
async function getAccessToken() {
  const accounts = msalInstance.getAllAccounts();
  
  const request = {
    scopes: ["api://payment-api/Payments.Read"],
    account: accounts[0]
  };
  
  try {
    // Try silent acquisition
    // Uses cached access token if valid
    // Uses refresh token if access token expired
    const response = await msalInstance.acquireTokenSilent(request);
    return response.accessToken;
    
  } catch (error) {
    // Silent acquisition failed (refresh token expired or revoked)
    // User must sign in again
    await msalInstance.acquireTokenPopup(request);
  }
}

Access Token vs ID Token: When to Use What

This confuses many developers. Here's the rule:

Access Token

Use for: Calling APIs Contains: Audience (aud) is the API Validate where: Backend API

// ✅ Correct: Frontend gets access token for API
const response = await msalInstance.acquireTokenSilent({
  scopes: ["api://payment-api/Payments.Read"]
});

// Send to API
fetch("https://api.mycompany.com/payments", {
  headers: {
    "Authorization": `Bearer ${response.accessToken}`  // Access token
  }
});

// ✅ Correct: API validates access token
const claims = await validateToken(accessToken);
console.log(claims.aud);  // "api://payment-api"

ID Token

Use for: Displaying user info in UI Contains: User identity claims Validate where: Frontend (but don't trust for authorization)

// ✅ Correct: Use ID token for UI
const response = await msalInstance.loginPopup({
  scopes: ["openid", "profile"]
});

const idToken = response.idToken;  // ID token
const account = response.account;

// Display in UI
console.log(`Welcome, ${account.name}!`);  // From ID token claims

// ❌ Wrong: Don't send ID token to API
fetch("https://api.mycompany.com/payments", {
  headers: {
    "Authorization": `Bearer ${response.idToken}`  // ❌ Wrong!
  }
});

Token Storage

Where you store tokens matters for security.

Frontend Storage

// ✅ MSAL handles storage automatically
const msalInstance = new PublicClientApplication({
  auth: { clientId: "..." },
  cache: {
    cacheLocation: "localStorage",  // or "sessionStorage"
    storeAuthStateInCookie: false
  }
});

// Tokens stored as:
// msal.{clientId}.accessToken.{tokenId}
// msal.{clientId}.idToken
// msal.{clientId}.refreshToken.{tokenId}

Security considerations:

• ✅ Use localStorage for convenience (persists across tabs)

• ✅ Use sessionStorage for higher security (clears on close)

• ❌ Never store in cookies (CSRF risk)

• ❌ Never store in URL/querystring

• ❌ Never log tokens

Backend Storage

// ✅ In-memory for short-lived tokens
const tokenCache = new Map<string, { token: string, expires: number }>();

// ✅ Encrypted database for refresh tokens
await db.refreshTokens.create({
  userId: user.id,
  token: encrypt(refreshToken),  // ✅ Encrypt!
  expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000)
});

// ✅ Azure Key Vault for extremely sensitive scenarios
const secret = await keyVaultClient.setSecret("refresh-token", refreshToken);

// ❌ Never in plain-text database
// ❌ Never in logs
// ❌ Never in source control

Token Claims and Customization

You can customize what appears in tokens.

Optional Claims

Azure Portal → App registration → Token configuration → Add optional claim

ID Token:
  ☑ email
  ☑ family_name
  ☑ given_name
  ☑ upn

Access Token:
  ☑ email
  ☑ groups    // ⚠️ Beware: can make token large

App Roles

Define roles in your app manifest:

// App registration → Manifest
{
  "appRoles": [
    {
      "allowedMemberTypes": ["User"],
      "description": "Finance team members",
      "displayName": "Finance",
      "id": "guid-1",
      "isEnabled": true,
      "lang": null,
      "origin": "Application",
      "value": "Finance"
    },
    {
      "allowedMemberTypes": ["User"],
      "description": "Admin users",
      "displayName": "Admin",
      "id": "guid-2",
      "isEnabled": true,
      "value": "Admin"
    }
  ]
}

Tokens will include:

{
  "roles": ["Finance", "Admin"]
}

Groups Claims

// Enable groups overage claim
// Token configuration → Groups claim → Security groups

// Tokens include:
{
  "groups": [
    "aa11bb22-...",  // Finance group
    "cc33dd44-..."   // Support group
  ]
}

// Or if > 200 groups:
{
  "_claim_names": {
    "groups": "src1"
  },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://graph.microsoft.com/v1.0/me/getMemberObjects"
    }
  }
}

// Must call endpoint to get full group list

Common Pitfalls

Pitfall 1: Not Caching JWKS

// ❌ Fetches JWKS on every validation
async function validate(token: string) {
  const response = await fetch(jwksUri);  // Network call every time!
  const keys = await response.json();
  // ...
}

// ✅ Cache JWKS
const jwksClient = jwks.Client({
  jwksUri,
  cache: true,
  cacheMaxAge: 86400000
});

Pitfall 2: Trusting Decoded Tokens

// ❌ Just decode, don't verify
const decoded = jwt.decode(token);
const userId = decoded.sub;  // Not verified!

// ✅ Always verify
const verified = jwt.verify(token, publicKey, { audience, issuer });
const userId = verified.sub;

Pitfall 3: Logging Tokens

// ❌ Never log tokens
console.log(`Token: ${accessToken}`);
logger.info(`Refresh token: ${refreshToken}`);

// ✅ Log token metadata only
console.log(`Token expired: ${jwt.decode(token).exp < Date.now() / 1000}`);

Pitfall 4: Wrong Token for Purpose

// ❌ Using ID token for API calls
fetch(apiUrl, {
  headers: { "Authorization": `Bearer ${idToken}` }
});

// ✅ Use access token for APIs
fetch(apiUrl, {
  headers: { "Authorization": `Bearer ${accessToken}` }
});

Key Takeaways

1. Three Token Types: Access (call APIs), ID (user identity), Refresh (get new tokens)

2. Always Validate: Signature, issuer, audience, expiration

3. Cache JWKS: Huge performance improvement

4. Handle Key Rotation: Clear cache and retry if kid not found

5. Store Securely: Memory/encrypted DB, never plain text

6. Right Token for Job: Access token for APIs, ID token for UI

7. Never Log Tokens: Security critical

What's Next

In Part 5: API Permissions and Consent, we'll explore:

• Delegated vs application permissions

• Microsoft Graph permissions

• Admin consent vs user consent

• Permission scopes and least privilege

• Consent frameworks

• Pre-authorization patterns

Understanding tokens is foundational. Next, we'll see how permissions control what those tokens can do.

---

Previous: Part 3: Authentication Protocols and Flows Next: Part 5: API Permissions and Consent Back to Series Overview