Auth at the Gateway

Why Auth Belongs at the Gateway

Implementing auth in every service creates drift. Service A uses HS256 JWTs, Service B uses RS256, Service C forgot to check token expiry. The gateway centralizes this:

• One place to update signing keys
• One place to change token format
• Services receive pre-verified identity in headers — X-User-Id, X-User-Role

Services can still do authorization (can this user access this resource?) but authentication (is this a valid user?) lives at the edge.

JWT Verification

// Gateway middleware — runs before every proxied request
import jwt from 'jsonwebtoken';
import { createRemoteJWKSet, jwtVerify } from 'jose';

// For RS256: fetch public keys from JWKS endpoint
const JWKS = createRemoteJWKSet(new URL('https://auth.yourapp.com/.well-known/jwks.json'));

async function verifyJWT(req: Request, res: Response, next: NextFunction) {
	const authHeader = req.headers['authorization'];
	if (!authHeader?.startsWith('Bearer ')) {
		return res.status(401).json({ error: 'Missing token' });
	}

	const token = authHeader.slice(7);

	try {
		const { payload } = await jwtVerify(token, JWKS, {
			issuer: 'https://auth.yourapp.com',
			audience: 'api'
		});

		// Forward verified identity to backend services
		req.headers['x-user-id'] = payload.sub as string;
		req.headers['x-user-role'] = payload.role as string;
		req.headers['x-user-email'] = payload.email as string;

		// Remove raw JWT — services don't need it
		delete req.headers['authorization'];

		next();
	} catch (err) {
		return res.status(401).json({ error: 'Invalid token' });
	}
}

Backend service — just reads headers, no crypto:

app.get('/api/orders', (req, res) => {
	const userId = req.headers['x-user-id'];
	const role = req.headers['x-user-role'];

	// No JWT parsing — gateway already verified
	const orders = await db.orders.findByUser(userId);
	res.json(orders);
});

API Key Auth

For machine-to-machine or developer API access:

interface ApiKey {
	id: string;
	hashedKey: string;
	ownerId: string;
	scopes: string[];
	rateLimit: number; // requests per minute
}

async function verifyApiKey(req: Request, res: Response, next: NextFunction) {
	const key = (req.headers['x-api-key'] as string) ?? (req.query.api_key as string);

	if (!key) {
		return res.status(401).json({ error: 'API key required' });
	}

	// Hash the incoming key and compare against stored hashes
	// Never store plaintext API keys
	const keyHash = hashApiKey(key);
	const apiKey = await db.apiKeys.findByHash(keyHash);

	if (!apiKey) {
		return res.status(401).json({ error: 'Invalid API key' });
	}

	// Forward identity
	req.headers['x-owner-id'] = apiKey.ownerId;
	req.headers['x-scopes'] = apiKey.scopes.join(',');

	// Apply key-specific rate limit
	req.rateLimit = apiKey.rateLimit;

	next();
}

function hashApiKey(key: string): string {
	return crypto.createHash('sha256').update(key).digest('hex');
}

OAuth Token Introspection

When tokens are opaque (not self-contained JWTs), the gateway calls the auth server to validate them:

async function introspectToken(token: string): Promise<TokenInfo | null> {
	const response = await fetch('https://auth.yourapp.com/oauth/introspect', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/x-www-form-urlencoded',
			Authorization: `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`
		},
		body: new URLSearchParams({ token })
	});

	const data = await response.json();
	if (!data.active) return null;

	return {
		sub: data.sub,
		scope: data.scope,
		exp: data.exp
	};
}

// Cache introspection results — don't call auth server on every request
const introspectCached = memoize(introspectToken, {
	ttl: 30_000, // 30s cache — balance freshness vs load
	keyFn: (token) => token
});

Route-Level Auth Policies

Different routes have different requirements:

type AuthPolicy =
	| { type: 'public' }
	| { type: 'jwt'; roles?: string[] }
	| { type: 'api-key'; scopes?: string[] }
	| { type: 'any' }; // jwt or api-key

const routePolicies: Array<{ pattern: RegExp; method?: string; policy: AuthPolicy }> = [
	{ pattern: /^\/health$/, policy: { type: 'public' } },
	{ pattern: /^\/api\/public\//, policy: { type: 'public' } },
	{ pattern: /^\/api\/admin\//, policy: { type: 'jwt', roles: ['admin'] } },
	{ pattern: /^\/api\/v1\//, policy: { type: 'any' } }
];

async function authMiddleware(req: Request, res: Response, next: NextFunction) {
	const policy = routePolicies.find((r) => r.pattern.test(req.path))?.policy ?? { type: 'jwt' }; // default: require JWT

	if (policy.type === 'public') return next();

	// ... check based on policy type
}

Forwarding Identity Securely

Backend services must only trust these headers from the gateway — not from external clients. Ensure your internal network topology prevents external clients from setting these headers directly:

// Strip any x-user-* headers from the original request
// before applying gateway-set values
function sanitizeInternalHeaders(req: Request): void {
	const internal = ['x-user-id', 'x-user-role', 'x-user-email', 'x-owner-id'];
	for (const header of internal) {
		delete req.headers[header];
	}
}

// Apply in order: sanitize first, then set from verified token
app.use(sanitizeInternalHeaders);
app.use(verifyJWT);

If your services are publicly reachable (not just via gateway), they must still verify these headers came from a trusted source — use mTLS or a shared internal secret to sign gateway requests.