Part 6: Protecting APIs with Microsoft Entra ID

Learn how to secure your APIs with MS Entra ID authentication, implement token validation middleware, handle scopes and permissions, and build production-ready API protection

Introduction

After building several microservices for a payment processing platform, I learned that securing APIs isn't just about validating tokens—it's about building a comprehensive defense strategy that handles authentication, authorization, multi-tenancy, and edge cases gracefully. In this part, I'll share the patterns and practices I've developed for protecting APIs with MS Entra ID.

When I first started securing APIs with MS Entra, I made the classic mistake of thinking token validation was enough. But production taught me that you need proper scope validation, tenant isolation, error handling, token caching, and performance optimization. Let me show you how to build production-ready API protection.

Prerequisites

Before diving in, you should be familiar with:

• MS Entra fundamentals (Part 1)

• Authentication flows (Part 3)

• Token structure and validation (Part 4)

• API permissions (Part 5)

• Express.js and Node.js

• REST API concepts

API Protection Fundamentals

The Defense-in-Depth Approach

Here's the multi-layer security strategy I use:

┌─────────────────────────────────────────┐
│         Network Layer (Azure)           │
│   • API Gateway                         │
│   • Rate Limiting                       │
│   • DDoS Protection                     │
└─────────────┬───────────────────────────┘
              │
┌─────────────▼───────────────────────────┐
│       Authentication Layer              │
│   • Token Validation                    │
│   • Signature Verification              │
│   • Issuer/Audience Checks              │
└─────────────┬───────────────────────────┘
              │
┌─────────────▼───────────────────────────┐
│       Authorization Layer               │
│   • Scope Validation                    │
│   • Role Validation                     │
│   • Tenant Isolation                    │
└─────────────┬───────────────────────────┘
              │
┌─────────────▼───────────────────────────┐
│        Business Logic Layer             │
│   • Resource-level Authorization        │
│   • Data Filtering                      │
│   • Audit Logging                       │
└─────────────────────────────────────────┘

Building the Token Validation Middleware

Complete Validation Middleware

Here's the production-ready middleware I use:

// src/middleware/auth.middleware.ts
import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';
import { promisify } from 'util';

export interface AuthConfig {
  tenantId: string;
  clientId: string;
  audience?: string;  // Optional: defaults to clientId
  issuer?: string;    // Optional: defaults to MS Entra issuer
  validateScopes?: boolean;
  requiredScopes?: string[];
  allowMultiTenant?: boolean;
  validateRoles?: boolean;
  requiredRoles?: string[];
}

export interface AuthenticatedUser {
  oid: string;          // Object ID
  tid: string;          // Tenant ID
  upn?: string;         // User Principal Name
  name?: string;        // Display name
  email?: string;       // Email
  scopes: string[];     // Token scopes
  roles: string[];      // App roles
  tokenType: 'user' | 'application';
}

// Extend Express Request
declare global {
  namespace Express {
    interface Request {
      user?: AuthenticatedUser;
      token?: string;
    }
  }
}

export class AuthMiddleware {
  private jwksClient: jwksClient.JwksClient;
  private config: AuthConfig;
  private getSigningKey: (kid: string) => Promise<string>;

  constructor(config: AuthConfig) {
    this.config = config;

    // Initialize JWKS client with caching
    this.jwksClient = jwksClient({
      jwksUri: `https://login.microsoftonline.com/${config.tenantId}/discovery/v2.0/keys`,
      cache: true,
      cacheMaxEntries: 10,
      cacheMaxAge: 600000, // 10 minutes
      rateLimit: true,
      jwksRequestsPerMinute: 10,
    });

    // Promisify the getSigningKey method
    this.getSigningKey = promisify((kid: string, callback: any) => {
      this.jwksClient.getSigningKey(kid, (err, key) => {
        if (err) return callback(err);
        const signingKey = key.getPublicKey();
        callback(null, signingKey);
      });
    });
  }

  /**
   * Main authentication middleware
   */
  authenticate = () => {
    return async (req: Request, res: Response, next: NextFunction) => {
      try {
        // Extract token
        const token = this.extractToken(req);
        if (!token) {
          return res.status(401).json({
            error: 'unauthorized',
            message: 'No authentication token provided',
          });
        }

        // Decode token header to get kid
        const decodedHeader = jwt.decode(token, { complete: true });
        if (!decodedHeader || typeof decodedHeader === 'string') {
          return res.status(401).json({
            error: 'invalid_token',
            message: 'Invalid token format',
          });
        }

        const { kid } = decodedHeader.header;
        if (!kid) {
          return res.status(401).json({
            error: 'invalid_token',
            message: 'Token missing key ID',
          });
        }

        // Get signing key
        const signingKey = await this.getSigningKey(kid);

        // Verify and decode token
        const decoded = jwt.verify(token, signingKey, {
          algorithms: ['RS256'],
          audience: this.config.audience || this.config.clientId,
          issuer: this.config.issuer || 
                  `https://login.microsoftonline.com/${this.config.tenantId}/v2.0`,
        }) as any;

        // Validate tenant (if not multi-tenant)
        if (!this.config.allowMultiTenant && decoded.tid !== this.config.tenantId) {
          return res.status(403).json({
            error: 'forbidden',
            message: 'Token from unauthorized tenant',
          });
        }

        // Extract user information
        const user: AuthenticatedUser = {
          oid: decoded.oid,
          tid: decoded.tid,
          upn: decoded.upn,
          name: decoded.name,
          email: decoded.email || decoded.preferred_username,
          scopes: this.extractScopes(decoded),
          roles: decoded.roles || [],
          tokenType: decoded.idtyp === 'app' ? 'application' : 'user',
        };

        // Validate scopes if required
        if (this.config.validateScopes && this.config.requiredScopes) {
          if (!this.hasRequiredScopes(user.scopes, this.config.requiredScopes)) {
            return res.status(403).json({
              error: 'insufficient_scope',
              message: 'Token does not have required scopes',
              required: this.config.requiredScopes,
              provided: user.scopes,
            });
          }
        }

        // Validate roles if required
        if (this.config.validateRoles && this.config.requiredRoles) {
          if (!this.hasRequiredRoles(user.roles, this.config.requiredRoles)) {
            return res.status(403).json({
              error: 'insufficient_permissions',
              message: 'User does not have required roles',
              required: this.config.requiredRoles,
              provided: user.roles,
            });
          }
        }

        // Attach user to request
        req.user = user;
        req.token = token;

        next();
      } catch (error) {
        console.error('Authentication error:', error);

        if (error instanceof jwt.TokenExpiredError) {
          return res.status(401).json({
            error: 'token_expired',
            message: 'Authentication token has expired',
          });
        }

        if (error instanceof jwt.JsonWebTokenError) {
          return res.status(401).json({
            error: 'invalid_token',
            message: 'Invalid authentication token',
          });
        }

        return res.status(500).json({
          error: 'internal_error',
          message: 'Authentication failed',
        });
      }
    };
  };

  /**
   * Extract token from request
   */
  private extractToken(req: Request): string | null {
    const authHeader = req.headers.authorization;
    if (!authHeader) return null;

    const parts = authHeader.split(' ');
    if (parts.length !== 2 || parts[0] !== 'Bearer') {
      return null;
    }

    return parts[1];
  }

  /**
   * Extract scopes from token
   */
  private extractScopes(decoded: any): string[] {
    // Delegated permissions (user tokens)
    if (decoded.scp) {
      return decoded.scp.split(' ');
    }

    // Application permissions (app tokens)
    if (decoded.roles) {
      return decoded.roles;
    }

    return [];
  }

  /**
   * Check if token has required scopes
   */
  private hasRequiredScopes(userScopes: string[], requiredScopes: string[]): boolean {
    return requiredScopes.every(scope => userScopes.includes(scope));
  }

  /**
   * Check if user has required roles
   */
  private hasRequiredRoles(userRoles: string[], requiredRoles: string[]): boolean {
    return requiredRoles.some(role => userRoles.includes(role));
  }
}

Using the Authentication Middleware

Here's how I use this middleware in my APIs:

// src/app.ts
import express from 'express';
import { AuthMiddleware } from './middleware/auth.middleware';

const app = express();

// Initialize auth middleware
const authMiddleware = new AuthMiddleware({
  tenantId: process.env.ENTRA_TENANT_ID!,
  clientId: process.env.ENTRA_CLIENT_ID!,
  allowMultiTenant: false,
});

// Apply to all routes
app.use('/api', authMiddleware.authenticate());

// Or apply to specific routes
app.get('/api/public/health', (req, res) => {
  res.json({ status: 'healthy' });
});

app.get('/api/protected/data', 
  authMiddleware.authenticate(),
  (req, res) => {
    res.json({ 
      message: 'Protected data',
      user: req.user 
    });
  }
);

Scope-Based Authorization

Scope Validation Middleware

Here's how I implement fine-grained scope validation:

// src/middleware/scope.middleware.ts
import { Request, Response, NextFunction } from 'express';

export type ScopeRequirement = string | string[] | ScopeRule;

export interface ScopeRule {
  anyOf?: string[];
  allOf?: string[];
  noneOf?: string[];
}

/**
 * Middleware to require specific scopes
 */
export function requireScopes(...scopes: string[]) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return res.status(401).json({
        error: 'unauthorized',
        message: 'Authentication required',
      });
    }

    const userScopes = req.user.scopes;
    const hasRequiredScopes = scopes.every(scope => userScopes.includes(scope));

    if (!hasRequiredScopes) {
      return res.status(403).json({
        error: 'insufficient_scope',
        message: 'Required scopes not present',
        required: scopes,
        provided: userScopes,
      });
    }

    next();
  };
}

/**
 * Middleware to require any of the specified scopes
 */
export function requireAnyScope(...scopes: string[]) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return res.status(401).json({
        error: 'unauthorized',
        message: 'Authentication required',
      });
    }

    const userScopes = req.user.scopes;
    const hasAnyScope = scopes.some(scope => userScopes.includes(scope));

    if (!hasAnyScope) {
      return res.status(403).json({
        error: 'insufficient_scope',
        message: 'At least one required scope must be present',
        required: scopes,
        provided: userScopes,
      });
    }

    next();
  };
}

/**
 * Advanced scope validation with complex rules
 */
export function validateScopes(rule: ScopeRule) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return res.status(401).json({
        error: 'unauthorized',
        message: 'Authentication required',
      });
    }

    const userScopes = req.user.scopes;

    // Check allOf (must have all)
    if (rule.allOf) {
      const hasAll = rule.allOf.every(scope => userScopes.includes(scope));
      if (!hasAll) {
        return res.status(403).json({
          error: 'insufficient_scope',
          message: 'Missing required scopes',
          rule: 'allOf',
          required: rule.allOf,
        });
      }
    }

    // Check anyOf (must have at least one)
    if (rule.anyOf) {
      const hasAny = rule.anyOf.some(scope => userScopes.includes(scope));
      if (!hasAny) {
        return res.status(403).json({
          error: 'insufficient_scope',
          message: 'At least one scope required',
          rule: 'anyOf',
          required: rule.anyOf,
        });
      }
    }

    // Check noneOf (must not have any)
    if (rule.noneOf) {
      const hasNone = rule.noneOf.every(scope => !userScopes.includes(scope));
      if (!hasNone) {
        return res.status(403).json({
          error: 'forbidden_scope',
          message: 'Token contains forbidden scopes',
          rule: 'noneOf',
          forbidden: rule.noneOf,
        });
      }
    }

    next();
  };
}

Using Scope Middleware

Here's how I use these scope validators:

// src/routes/payments.routes.ts
import { Router } from 'express';
import { requireScopes, requireAnyScope, validateScopes } from '../middleware/scope.middleware';

const router = Router();

// Simple scope requirement
router.get('/payments',
  requireScopes('Payments.Read'),
  async (req, res) => {
    // User must have Payments.Read scope
    const payments = await getPayments(req.user!.oid);
    res.json(payments);
  }
);

// Multiple required scopes
router.post('/payments',
  requireScopes('Payments.Write', 'Transactions.Create'),
  async (req, res) => {
    // User must have both scopes
    const payment = await createPayment(req.body);
    res.json(payment);
  }
);

// Any of multiple scopes
router.get('/reports',
  requireAnyScope('Reports.Read', 'Reports.Admin', 'Admin.Full'),
  async (req, res) => {
    // User must have at least one of these scopes
    const reports = await getReports();
    res.json(reports);
  }
);

// Complex scope rules
router.put('/payments/:id',
  validateScopes({
    allOf: ['Payments.Write'],           // Must have write
    anyOf: ['Payments.Update', 'Admin.Full'],  // And either update or admin
    noneOf: ['Payments.ReadOnly']        // But not read-only
  }),
  async (req, res) => {
    const payment = await updatePayment(req.params.id, req.body);
    res.json(payment);
  }
);

export default router;

Role-Based Authorization

Role Validation Middleware

Here's my role-based authorization implementation:

// src/middleware/role.middleware.ts
import { Request, Response, NextFunction } from 'express';

/**
 * Middleware to require specific roles
 */
export function requireRoles(...roles: string[]) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return res.status(401).json({
        error: 'unauthorized',
        message: 'Authentication required',
      });
    }

    const userRoles = req.user.roles;
    const hasRequiredRoles = roles.some(role => userRoles.includes(role));

    if (!hasRequiredRoles) {
      return res.status(403).json({
        error: 'insufficient_permissions',
        message: 'Required role not present',
        required: roles,
        provided: userRoles,
      });
    }

    next();
  };
}

/**
 * Middleware to require all specified roles
 */
export function requireAllRoles(...roles: string[]) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return res.status(401).json({
        error: 'unauthorized',
        message: 'Authentication required',
      });
    }

    const userRoles = req.user.roles;
    const hasAllRoles = roles.every(role => userRoles.includes(role));

    if (!hasAllRoles) {
      return res.status(403).json({
        error: 'insufficient_permissions',
        message: 'All required roles must be present',
        required: roles,
        provided: userRoles,
      });
    }

    next();
  };
}

/**
 * Check if user has specific role
 */
export function hasRole(req: Request, role: string): boolean {
  return req.user?.roles.includes(role) || false;
}

/**
 * Check if user has any of the specified roles
 */
export function hasAnyRole(req: Request, roles: string[]): boolean {
  return roles.some(role => req.user?.roles.includes(role)) || false;
}

Combined Scope and Role Authorization

Here's how I combine scopes and roles for comprehensive authorization:

// src/routes/admin.routes.ts
import { Router } from 'express';
import { requireScopes } from '../middleware/scope.middleware';
import { requireRoles, hasRole } from '../middleware/role.middleware';

const router = Router();

// Require both scope and role
router.get('/admin/users',
  requireScopes('Admin.Read'),
  requireRoles('Admin', 'UserManager'),
  async (req, res) => {
    const users = await getAllUsers();
    res.json(users);
  }
);

// Different responses based on role
router.get('/admin/settings',
  requireScopes('Admin.Read'),
  async (req, res) => {
    const isFullAdmin = hasRole(req, 'Admin.Full');
    
    const settings = isFullAdmin 
      ? await getAllSettings()
      : await getUserSettings(req.user!.oid);
    
    res.json(settings);
  }
);

export default router;

Multi-Tenant API Protection

Tenant Isolation Middleware

For multi-tenant applications, here's how I ensure tenant isolation:

// src/middleware/tenant.middleware.ts
import { Request, Response, NextFunction } from 'express';

export interface TenantConfig {
  allowedTenants?: string[];  // Whitelist of tenant IDs
  requireTenantMatch?: boolean; // Require tenant in URL to match token
}

/**
 * Validate tenant from token
 */
export function validateTenant(config: TenantConfig = {}) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return res.status(401).json({
        error: 'unauthorized',
        message: 'Authentication required',
      });
    }

    const tokenTenantId = req.user.tid;

    // Check if tenant is in allowed list
    if (config.allowedTenants && !config.allowedTenants.includes(tokenTenantId)) {
      return res.status(403).json({
        error: 'forbidden',
        message: 'Tenant not authorized',
        tenantId: tokenTenantId,
      });
    }

    // Check if tenant in URL matches token
    if (config.requireTenantMatch) {
      const urlTenantId = req.params.tenantId || req.query.tenantId;
      if (urlTenantId && urlTenantId !== tokenTenantId) {
        return res.status(403).json({
          error: 'tenant_mismatch',
          message: 'Token tenant does not match requested tenant',
        });
      }
    }

    next();
  };
}

/**
 * Inject tenant context into request
 */
export function injectTenantContext() {
  return (req: Request, res: Response, next: NextFunction) => {
    if (req.user) {
      // Attach tenant ID for use in data queries
      (req as any).tenantId = req.user.tid;
    }
    next();
  };
}

Multi-Tenant Route Protection

Here's how I use tenant isolation in routes:

// src/routes/tenants.routes.ts
import { Router } from 'express';
import { validateTenant, injectTenantContext } from '../middleware/tenant.middleware';

const router = Router();

// Apply tenant context to all routes
router.use(injectTenantContext());

// Get tenant-specific data
router.get('/tenants/:tenantId/data',
  validateTenant({ requireTenantMatch: true }),
  async (req, res) => {
    const tenantId = (req as any).tenantId;
    
    // Query will automatically filter by tenant
    const data = await getTenantData(tenantId);
    res.json(data);
  }
);

// Whitelist specific tenants
router.get('/premium/features',
  validateTenant({ 
    allowedTenants: [
      'premium-tenant-1-id',
      'premium-tenant-2-id',
    ]
  }),
  async (req, res) => {
    const features = await getPremiumFeatures();
    res.json(features);
  }
);

export default router;

Error Handling and Security

Comprehensive Error Handler

Here's my production error handler:

// src/middleware/error.middleware.ts
import { Request, Response, NextFunction } from 'express';

export interface ApiError extends Error {
  status?: number;
  code?: string;
  details?: any;
}

/**
 * Global error handler
 */
export function errorHandler(
  err: ApiError,
  req: Request,
  res: Response,
  next: NextFunction
) {
  // Log error (but not sensitive token data)
  console.error('API Error:', {
    error: err.message,
    code: err.code,
    status: err.status,
    path: req.path,
    method: req.method,
    user: req.user?.oid,
    tenant: req.user?.tid,
  });

  // Don't leak error details in production
  const isProduction = process.env.NODE_ENV === 'production';

  const status = err.status || 500;
  const response: any = {
    error: err.code || 'internal_error',
    message: isProduction ? 'An error occurred' : err.message,
  };

  // Include details in non-production
  if (!isProduction && err.details) {
    response.details = err.details;
  }

  res.status(status).json(response);
}

/**
 * 404 handler
 */
export function notFoundHandler(req: Request, res: Response) {
  res.status(404).json({
    error: 'not_found',
    message: 'Endpoint not found',
    path: req.path,
  });
}

Performance Optimization

Token Caching Strategy

Here's how I optimize token validation performance:

// src/services/token-cache.service.ts
import NodeCache from 'node-cache';
import jwt from 'jsonwebtoken';

export class TokenCacheService {
  private cache: NodeCache;

  constructor(ttlSeconds: number = 300) { // 5 minutes default
    this.cache = new NodeCache({
      stdTTL: ttlSeconds,
      checkperiod: 60,
      useClones: false,
    });
  }

  /**
   * Get validated user from cache
   */
  get(token: string): any | null {
    try {
      // Use token hash as key (don't store full token)
      const key = this.hashToken(token);
      return this.cache.get(key) || null;
    } catch (error) {
      return null;
    }
  }

  /**
   * Cache validated user
   */
  set(token: string, user: any): void {
    try {
      const key = this.hashToken(token);
      
      // Decode token to get expiry
      const decoded = jwt.decode(token) as any;
      if (decoded && decoded.exp) {
        const now = Math.floor(Date.now() / 1000);
        const ttl = decoded.exp - now;
        
        // Cache until token expires (or max 5 minutes)
        this.cache.set(key, user, Math.min(ttl, 300));
      }
    } catch (error) {
      // Fail silently
    }
  }

  /**
   * Clear cache entry
   */
  delete(token: string): void {
    try {
      const key = this.hashToken(token);
      this.cache.del(key);
    } catch (error) {
      // Fail silently
    }
  }

  /**
   * Hash token for cache key
   */
  private hashToken(token: string): string {
    const crypto = require('crypto');
    return crypto.createHash('sha256').update(token).digest('hex');
  }

  /**
   * Get cache stats
   */
  getStats() {
    return this.cache.getStats();
  }
}

Optimized Middleware with Caching

Here's the middleware with caching integrated:

// src/middleware/auth-cached.middleware.ts
import { Request, Response, NextFunction } from 'express';
import { AuthMiddleware, AuthConfig } from './auth.middleware';
import { TokenCacheService } from '../services/token-cache.service';

export class CachedAuthMiddleware extends AuthMiddleware {
  private tokenCache: TokenCacheService;

  constructor(config: AuthConfig, cacheTTL: number = 300) {
    super(config);
    this.tokenCache = new TokenCacheService(cacheTTL);
  }

  /**
   * Authentication middleware with caching
   */
  authenticate = () => {
    return async (req: Request, res: Response, next: NextFunction) => {
      try {
        const token = this.extractToken(req);
        if (!token) {
          return res.status(401).json({
            error: 'unauthorized',
            message: 'No authentication token provided',
          });
        }

        // Check cache first
        const cachedUser = this.tokenCache.get(token);
        if (cachedUser) {
          req.user = cachedUser;
          req.token = token;
          return next();
        }

        // Validate token (calls parent method)
        await super.authenticate()(req, res, (err?: any) => {
          if (err) return next(err);
          
          // Cache validated user
          if (req.user) {
            this.tokenCache.set(token, req.user);
          }
          
          next();
        });
      } catch (error) {
        next(error);
      }
    };
  };

  private extractToken(req: Request): string | null {
    const authHeader = req.headers.authorization;
    if (!authHeader) return null;
    const parts = authHeader.split(' ');
    if (parts.length !== 2 || parts[0] !== 'Bearer') return null;
    return parts[1];
  }
}

Complete API Example

Putting It All Together

Here's a complete API implementation:

// src/app.ts
import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import { CachedAuthMiddleware } from './middleware/auth-cached.middleware';
import { errorHandler, notFoundHandler } from './middleware/error.middleware';
import { injectTenantContext } from './middleware/tenant.middleware';

// Import routes
import paymentsRouter from './routes/payments.routes';
import adminRouter from './routes/admin.routes';
import tenantsRouter from './routes/tenants.routes';

const app = express();

// Security headers
app.use(helmet());

// CORS configuration
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
  credentials: true,
}));

// Body parsing
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Initialize auth middleware
const authMiddleware = new CachedAuthMiddleware({
  tenantId: process.env.ENTRA_TENANT_ID!,
  clientId: process.env.ENTRA_CLIENT_ID!,
  allowMultiTenant: process.env.ALLOW_MULTI_TENANT === 'true',
}, 300); // 5 minute cache

// Public routes
app.get('/health', (req, res) => {
  res.json({ status: 'healthy', timestamp: new Date().toISOString() });
});

app.get('/api/public/info', (req, res) => {
  res.json({
    name: 'Payment API',
    version: '1.0.0',
    auth: 'MS Entra ID',
  });
});

// Protected routes - apply auth globally
app.use('/api/protected', authMiddleware.authenticate());

// Inject tenant context
app.use('/api/protected', injectTenantContext());

// Register route handlers
app.use('/api/protected/payments', paymentsRouter);
app.use('/api/protected/admin', adminRouter);
app.use('/api/protected/tenants', tenantsRouter);

// Error handling
app.use(notFoundHandler);
app.use(errorHandler);

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`API server running on port ${PORT}`);
  console.log(`Auth: MS Entra ID (Tenant: ${process.env.ENTRA_TENANT_ID})`);
});

export default app;

Environment Configuration

# .env
NODE_ENV=production
PORT=3000

# MS Entra Configuration
ENTRA_TENANT_ID=your-tenant-id
ENTRA_CLIENT_ID=your-api-client-id
ALLOW_MULTI_TENANT=false

# CORS
ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com

# Logging
LOG_LEVEL=info

Testing Protected APIs

Testing with cURL

# Get access token first
TOKEN=$(curl -X POST \
  "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=$API_SCOPE" \
  -d "grant_type=client_credentials" \
  | jq -r '.access_token')

# Call protected API
curl -X GET "https://api.example.com/api/protected/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Testing with Postman

// Postman Pre-request Script
const tenantId = pm.environment.get('TENANT_ID');
const clientId = pm.environment.get('CLIENT_ID');
const clientSecret = pm.environment.get('CLIENT_SECRET');
const scope = pm.environment.get('API_SCOPE');

// Get cached token
const cachedToken = pm.environment.get('access_token');
const tokenExpiry = pm.environment.get('token_expiry');

// Check if token is still valid
if (cachedToken && tokenExpiry && Date.now() < parseInt(tokenExpiry)) {
  console.log('Using cached token');
  pm.request.headers.add({
    key: 'Authorization',
    value: `Bearer ${cachedToken}`
  });
} else {
  // Get new token
  pm.sendRequest({
    url: `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`,
    method: 'POST',
    header: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: {
      mode: 'urlencoded',
      urlencoded: [
        { key: 'client_id', value: clientId },
        { key: 'client_secret', value: clientSecret },
        { key: 'scope', value: scope },
        { key: 'grant_type', value: 'client_credentials' }
      ]
    }
  }, (err, response) => {
    if (err) {
      console.error('Token request failed:', err);
    } else {
      const token = response.json().access_token;
      const expiresIn = response.json().expires_in;
      
      // Cache token
      pm.environment.set('access_token', token);
      pm.environment.set('token_expiry', Date.now() + (expiresIn * 1000));
      
      // Use token
      pm.request.headers.add({
        key: 'Authorization',
        value: `Bearer ${token}`
      });
    }
  });
}

Automated Testing

// tests/api-auth.test.ts
import request from 'supertest';
import app from '../src/app';
import { generateTestToken } from './helpers/token-generator';

describe('API Authentication', () => {
  let validToken: string;
  let expiredToken: string;
  let invalidToken: string;

  beforeAll(async () => {
    validToken = await generateTestToken({
      oid: 'test-user-id',
      tid: process.env.ENTRA_TENANT_ID!,
      scopes: ['Payments.Read', 'Payments.Write'],
      roles: ['User'],
    });

    expiredToken = await generateTestToken({
      oid: 'test-user-id',
      tid: process.env.ENTRA_TENANT_ID!,
      scopes: ['Payments.Read'],
      exp: Math.floor(Date.now() / 1000) - 3600, // Expired 1 hour ago
    });

    invalidToken = 'invalid.token.here';
  });

  describe('Token Validation', () => {
    it('should reject request without token', async () => {
      const response = await request(app)
        .get('/api/protected/payments')
        .expect(401);

      expect(response.body.error).toBe('unauthorized');
    });

    it('should reject invalid token', async () => {
      const response = await request(app)
        .get('/api/protected/payments')
        .set('Authorization', `Bearer ${invalidToken}`)
        .expect(401);

      expect(response.body.error).toBe('invalid_token');
    });

    it('should reject expired token', async () => {
      const response = await request(app)
        .get('/api/protected/payments')
        .set('Authorization', `Bearer ${expiredToken}`)
        .expect(401);

      expect(response.body.error).toBe('token_expired');
    });

    it('should accept valid token', async () => {
      const response = await request(app)
        .get('/api/protected/payments')
        .set('Authorization', `Bearer ${validToken}`)
        .expect(200);

      expect(response.body).toBeDefined();
    });
  });

  describe('Scope Validation', () => {
    it('should reject insufficient scopes', async () => {
      const limitedToken = await generateTestToken({
        oid: 'test-user-id',
        tid: process.env.ENTRA_TENANT_ID!,
        scopes: ['Payments.Read'],  // Missing Payments.Write
        roles: ['User'],
      });

      const response = await request(app)
        .post('/api/protected/payments')
        .set('Authorization', `Bearer ${limitedToken}`)
        .send({ amount: 100 })
        .expect(403);

      expect(response.body.error).toBe('insufficient_scope');
    });

    it('should accept sufficient scopes', async () => {
      const response = await request(app)
        .post('/api/protected/payments')
        .set('Authorization', `Bearer ${validToken}`)
        .send({ amount: 100 })
        .expect(200);

      expect(response.body).toBeDefined();
    });
  });
});

Production Best Practices

1. Rate Limiting

import rateLimit from 'express-rate-limit';

// Global rate limiter
const globalLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // 100 requests per window
  message: 'Too many requests, please try again later',
  standardHeaders: true,
  legacyHeaders: false,
});

// Stricter limiter for auth endpoints
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5,
  skipSuccessfulRequests: true,
});

app.use('/api', globalLimiter);
app.use('/api/auth', authLimiter);

2. Security Headers

import helmet from 'helmet';

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
    },
  },
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true,
    preload: true,
  },
}));

3. Request Logging

// src/middleware/logging.middleware.ts
import { Request, Response, NextFunction } from 'express';
import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' }),
  ],
});

export function requestLogger(req: Request, res: Response, next: NextFunction) {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    
    logger.info('API Request', {
      method: req.method,
      path: req.path,
      status: res.statusCode,
      duration,
      user: req.user?.oid,
      tenant: req.user?.tid,
      ip: req.ip,
    });
  });

  next();
}

4. Health Checks

// src/routes/health.routes.ts
import { Router } from 'express';

const router = Router();

router.get('/health', (req, res) => {
  res.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
  });
});

router.get('/health/ready', async (req, res) => {
  try {
    // Check dependencies
    await checkDatabase();
    await checkRedis();
    
    res.json({ status: 'ready' });
  } catch (error) {
    res.status(503).json({ status: 'not ready', error: error.message });
  }
});

export default router;

Key Takeaways

1. Defense in Depth: Layer multiple security controls (authentication → authorization → business logic)

2. Token Validation: Always validate signature, issuer, audience, and expiration

3. Scope Validation: Implement fine-grained scope checking for API operations

4. Role-Based Access: Use app roles for coarse-grained permissions

5. Tenant Isolation: Enforce strict tenant boundaries in multi-tenant systems

6. Error Handling: Never leak sensitive information in error responses

7. Performance: Cache validated tokens and JWKS to reduce latency

8. Monitoring: Log auth events for security auditing

9. Testing: Automate authentication and authorization testing

10. Security Headers: Use Helmet and other security middleware

Common Pitfalls to Avoid

1. Trusting Client-Provided Tokens: Always validate server-side

2. Insufficient Scope Validation: Check scopes on every protected route

3. Tenant Leakage: Don't rely on client-provided tenant IDs

4. Caching Too Long: Balance performance with token freshness

5. Exposing Errors: Sanitize error messages in production

6. Missing Rate Limiting: Always implement rate limiting

7. Ignoring Token Expiration: Respect token lifetime

8. Hardcoded Configuration: Use environment variables

Next Steps

In Part 7: Advanced Features, we'll explore:

• Conditional Access policies

• Multi-factor authentication (MFA)

• Continuous Access Evaluation (CAE)

• Managed identities for Azure resources

• B2B and B2C scenarios

• Custom claims and token customization

• Enterprise application SSO

Additional Resources

• Azure AD Token Validation

• OAuth 2.0 Best Practices

• Express.js Security Best Practices

• OWASP API Security Top 10

---

This is part 6 of the MS Entra 101 Series. Continue to Part 7: Advanced Features to learn about advanced MS Entra capabilities.