This article addresses the architectural challenge of integrating Swagger UI with modern Backend-for-Frontend (BFF) architectures that prioritize security by avoiding tokens in the browser. It introduces a Swagger UI plugin designed to enable native communication with the BFF, respecting HTTP sessions, HttpOnly cookies, and CSRF protection, thus allowing Swagger UI to function as a first-class frontend client without compromising security.
Read original on DZone MicroservicesModern web security trends, driven by concerns like XSS attacks, stricter browser privacy policies, and updated OAuth recommendations, have led to a return to Backend-for-Frontend (BFF) architectures. This pattern centralizes token management on a trusted server, preventing token exfiltration and making the system more resilient to client-side attacks. Unlike direct API calls from SPAs that often expose access tokens to the browser, BFFs manage secure HTTP sessions and HttpOnly cookies, acting as confidential clients.
Swagger UI, by default, operates under a 'public client' assumption, making direct API calls from the browser and expecting to inject Bearer tokens into headers. This directly conflicts with the security posture of a BFF, which typically: (1) owns HTTP sessions and HttpOnly cookies, (2) provides CSRF protection, and (3) handles token management securely on the server. Attempting to use vanilla Swagger UI in a secure BFF environment often means bypassing essential security mechanisms or requiring complex proxying.
BFF vs. Public Client Mindset
BFFs are confidential clients that manage sessions, cookies, and tokens securely on the server, often using Authorization Code flow without PKCE. Swagger UI usually assumes a public client, making direct calls, injecting tokens into headers, and potentially requiring PKCE.
The article proposes treating Swagger UI as another frontend client within the BFF architecture. This is achieved by developing a Swagger UI plugin that leverages its official extension mechanism to adapt its behavior. This plugin ensures that Swagger UI: communicates exclusively with the BFF, relies on existing browser cookies and sessions, respects CSRF protection by including necessary headers, and does not require any changes to the OpenAPI specification itself. This approach avoids the need for back-end proxy layers or modifying the OpenAPI spec, keeping the architecture clean and secure.
This solution is backend-agnostic, demonstrated with Java/Spring but applicable to any stack that uses Swagger UI, such as .NET, Python, Go, or Node.js. It focuses on the secure handshake and communication, while acknowledging that managing HTTP session timeouts and access/refresh token lifetimes are security concerns that depend on specific application requirements and are outside the scope of the plugin itself.