The traditional single-page application token problem

A conventional single-page application (SPA) talking directly to Keycloak typically ends up holding an access token, and often a refresh token, somewhere in the browser — in memory, in local storage, or in a JavaScript-accessible cookie. Every one of these storage locations shares a common weakness: any malicious JavaScript running on that page, whether injected through a cross-site scripting vulnerability or hidden inside a compromised third-party library, can potentially read and exfiltrate those tokens. Modern web applications routinely load dozens of third-party scripts — analytics, advertising, customer support widgets — each one a potential avenue for exactly this kind of compromise.

What does the BFF pattern actually change?

The Backend-for-Frontend pattern introduces a dedicated server-side application, sitting between the browser and both the identity provider (Keycloak) and any backend APIs, that performs the OAuth/OpenID Connect login flow on the browser’s behalf, and holds the resulting tokens entirely on the server. The browser itself never receives the access or refresh token at all — instead, it receives a simple, traditional session cookie (ideally marked HttpOnly, meaning JavaScript cannot read it even if it wanted to), which the BFF uses to look up the corresponding tokens on its own server-side storage for every subsequent request.

Why is a cookie considered safer here than a token?

A well-configured session cookie — HttpOnly, marked Secure, with an appropriate SameSite attribute — is inaccessible to JavaScript entirely, meaning even a successful cross-site scripting attack cannot simply read it out of the page and exfiltrate it, unlike a token sitting in local storage or an ordinary, script-readable cookie. This doesn’t make the browser side of the application invulnerable to every possible attack, but it removes an entire, historically very common class of token theft that plagues traditional SPA architectures relying on direct, browser-held tokens.

Key vocabulary, explained simply

The BFF as a confidential OAuth client

From Keycloak’s own perspective, the BFF is registered as a standard confidential client — a client type that can securely hold a client secret because, unlike a browser-based SPA, it runs entirely on infrastructure the organization controls. This is a meaningful protocol-level distinction: a confidential client can use the full Authorization Code flow with a genuine client secret, generally considered a stronger configuration than the public-client patterns (with PKCE substituting for a secret) that a browser-based application would otherwise need to use on its own.

Where the authorization code flow actually happens

The entire OAuth Authorization Code exchange — redirecting to Keycloak, the user authenticating, Keycloak redirecting back with an authorization code, and that code being exchanged for tokens — happens entirely between the BFF and Keycloak, with the browser only ever seeing ordinary web page redirects, never the tokens themselves. This is a direct, deliberate application of the standard flow, simply relocated so that the party holding the resulting tokens is a trusted, server-side component rather than the browser.

Why this configuration is considered a best practice, not just one option among many

Current OAuth security guidance increasingly favors keeping tokens out of browser-accessible JavaScript contexts entirely, precisely because of the exfiltration risks discussed in the previous chapter. The BFF pattern is a direct, architecturally clean way to satisfy this guidance without abandoning a rich, single-page application user experience — the frontend still feels and behaves like a modern SPA, but the actual OAuth mechanics happen in a location fundamentally safer than the browser.

graph TB
    B[Browser / SPA] -->|HttpOnly session cookie| BFF[Backend-for-Frontend]
    BFF -->|Authorization Code flow| KC[Keycloak]
    KC -->|Access + Refresh Tokens| BFF
    BFF --> TS[Server-Side Token Store]
    BFF -->|injects access token| API[Backend APIs]
    B -->|API requests via cookie| BFF
    BFF -->|proxies request + token| API
    

Component breakdown

Where this is configured relative to Keycloak

Inside the Keycloak Admin Console, the BFF is registered as an ordinary confidential client, with its client authentication enabled and its redirect URIs pointed at the BFF’s own callback endpoint — not at the frontend’s client-side routes, since the entire authorization code exchange happens server-side within the BFF itself, never in the browser.

Why is horizontal scalability an architectural consideration here specifically?

Because the BFF holds session-to-token mappings, running more than one instance of it — necessary for handling real production load and providing redundancy — requires that server-side token store to be shared and consistent across instances, exactly analogous to how a clustered Keycloak deployment itself needs a shared session store. A BFF architecture that stores tokens only in a single instance’s local memory will break the moment a user’s requests are load-balanced across multiple BFF instances that don’t share that state.

What happens during initial login

When an unauthenticated user reaches the frontend, the BFF detects the absence of a valid session cookie and initiates the standard OAuth Authorization Code flow itself — redirecting the browser to Keycloak’s login page. Once the user authenticates and Keycloak redirects back with an authorization code, this redirect lands on the BFF’s own server-side callback endpoint, not on any frontend JavaScript route. The BFF exchanges the code for tokens directly with Keycloak, server-to-server, stores the resulting tokens in its token store under a newly generated session identifier, and sets an HttpOnly cookie containing that session identifier in the browser’s response.

What happens on every subsequent API request

For every request the frontend makes to what it believes is “the API,” it’s actually calling the BFF, which reads the session cookie automatically included by the browser, looks up the corresponding access token from its server-side store, and forwards the request onward to the actual backend API with that token correctly attached — typically as a standard bearer token in an Authorization header. The response is then relayed back to the frontend. From the frontend’s own code perspective, it’s simply making ordinary, same-origin API calls; the entire token-handling machinery is invisible to it.

Handling token refresh transparently

Because the BFF holds the refresh token as well, it can detect an expiring or expired access token and silently refresh it using the standard OAuth refresh flow, entirely on the server side, without the browser or frontend code needing to be aware this happened at all. This is a meaningful usability improvement over traditional SPA token handling, where the frontend itself typically needs its own logic to detect and handle token expiry and refresh.

Step-by-step: a full BFF-mediated request cycle

sequenceDiagram
    participant Browser
    participant BFF
    participant Keycloak
    participant API as Backend API

    Browser->>BFF: Initial page load, no session cookie
    BFF->>Keycloak: Redirects for login (Authorization Code flow)
    Browser->>Keycloak: User authenticates
    Keycloak->>BFF: Redirects back with authorization code
    BFF->>Keycloak: Exchanges code for tokens (server-to-server)
    Keycloak-->>BFF: Access + Refresh Tokens
    BFF->>BFF: Stores tokens, generates session ID
    BFF-->>Browser: Sets HttpOnly session cookie
    Browser->>BFF: Subsequent API call (cookie only)
    BFF->>API: Forwards request with real access token
    API-->>BFF: Response
    BFF-->>Browser: Relays response (no token ever exposed)
    

Notice, across this entire diagram, that the word “token” never appears on any arrow touching the browser directly — the browser’s involvement begins and ends with ordinary redirects and a simple cookie. This complete separation is the architectural core of the BFF pattern’s security value: there is simply no token present in the browser’s JavaScript context at any point for a cross-site scripting attack to steal.

The lifecycle of a BFF-managed session

CSRF protection is not optional

Because the BFF relies on cookie-based sessions, it inherits cookie-based authentication’s classic vulnerability: cross-site request forgery, where a malicious site tricks a user’s browser into making an unwanted request to the BFF, automatically including their valid session cookie. A BFF implementation must include explicit CSRF protection — typically a synchronizer token pattern or careful use of the SameSite cookie attribute — since this specific risk doesn’t naturally arise in the same way for a purely token-based architecture where a bearer token isn’t automatically attached by the browser to every request.

Securing the server-side token store

The BFF’s own token store becomes, in effect, a high-value target — anyone able to read from it gains access to real, valid tokens for every active session it holds. This store deserves strong access controls, encryption at rest where appropriate, and the same operational security discipline given to any other system holding sensitive credentials, rather than being treated as an incidental implementation detail.

The BFF as a new, security-relevant piece of attack surface

Introducing a new server-side component naturally introduces new attack surface of its own — the BFF’s own code, its dependencies, and its network exposure all deserve the same security scrutiny given to any other internet-facing service, since a vulnerability in the BFF itself (rather than in the frontend or Keycloak) could still provide an attacker a path to the tokens it holds.

Proven patterns

Anti-patterns to avoid

Best practices

Common mistakes