Create a BFF (Backend-for-Frontend) with Azure Functions

If your app is public-facing or must comply with OAuth 2.1 (which deprecates ROPC), use Authorization Code flow with PKCE instead. The BFF would then handle the redirect dance server-side. The Keycloak client must have "Direct Access Grants" enabled for ROPC.

Note: The reference files use blog-specific names (e.g., BACKEND_API_URL, proxy-entries). Adapt resource names, routes, and backend paths to your project's domain.

Architecture overview

Frontend (SPA)
    | fetch with credentials (cookies)
    v
BFF (Azure Functions v4)
    |-- Session Management (@hapi/iron sealed cookies)
    |-- CSRF Validation (X-Requested-With header)
    |-- CORS Handling (preflight + response headers)
    |-- Token Management (Keycloak OAuth2 ROPC)
    |   \-- Auto-refresh on expiry
    \-- Backend Proxy
        \-- Attach bearer token --> Backend API

Step-by-step implementation

Step 1: Scaffold the BFF directory

Create a bff/ directory at the project root with the structure below. Read references/project-setup.md for the exact file contents of package.json, tsconfig.json, host.json, and local.settings.json.

bff/
  src/
    index.ts              # Entry point - imports all function files
    lib/
      session.ts          # @hapi/iron seal/unseal + cookie helpers
      keycloak.ts         # OAuth2 ROPC auth, refresh, revoke
      cors.ts             # CORS preflight + response headers
      csrf.ts             # X-Requested-With header check
      proxy.ts            # Backend proxy with auto-refresh
    functions/
      auth-login.ts       # POST /api/auth/login
      auth-logout.ts      # POST /api/auth/logout
      auth-me.ts          # GET /api/auth/me
      auth-refresh.ts     # POST /api/auth/refresh
      proxy-*.ts          # One file per proxied resource
  package.json
  tsconfig.json
  host.json
  local.settings.json     # Not committed - env vars for local dev

Step 2: Implement shared libraries

Read references/lib-implementations.md when implementing this step -- it contains the exact source code for all five library files. Copy these as-is, then adapt environment variable names and backend URL patterns to the target project. The key design decisions:

1. session.ts - Uses @hapi/iron for symmetric encryption of { accessToken, refreshToken, expiresAt }. Cookie is httpOnly, Secure, SameSite=Lax. Includes decodeURIComponent() fallback because Azure SWA URL-encodes cookie values.

2. keycloak.ts - Resource Owner Password Credentials (ROPC) grant for login, refresh_token grant for renewal, token revocation for logout. Uses URLSearchParams for form-encoded bodies.

3. cors.ts - Every response includes Access-Control-Allow-Origin and Access-Control-Allow-Credentials: true. Preflight returns 204 with allowed methods and headers.

4. csrf.ts - Validates X-Requested-With: XMLHttpRequest on state-changing requests (POST, PUT). Returns 403 if missing.

5. proxy.ts - Extracts session from cookie, auto-refreshes if expired, attaches bearer token, forwards request to backend. Returns refreshed cookie if token was renewed.

Step 3: Implement Azure Function endpoints

Read references/function-implementations.md when implementing this step -- it contains complete source code for all auth and proxy functions. Adapt the proxy endpoints to your domain's resources. Every function follows this pattern:

async function handler(request: HttpRequest): Promise<HttpResponseInit> {
  // 1. Handle CORS preflight
  const preflight = handlePreflight(request);
  if (preflight) return preflight;

  // 2. Check CSRF (only for state-changing methods)
  if (request.method === "POST" || request.method === "PUT") {
    const csrfError = checkCsrf(request);
    if (csrfError) return { ...csrfError, headers: corsHeaders }; // CORS on errors too!
  }

  // 3. Do the work (auth or proxy)
  // 4. Return response with corsHeaders and cookies array
}

app.http("function-name", {
  methods: ["POST", "OPTIONS"], // Always include OPTIONS
  authLevel: "anonymous",
  route: "your/route",
  handler,
});

Step 4: Register all functions in index.ts

The entry point must import every function file so Azure Functions discovers them:

import "./functions/auth-login.js";
import "./functions/auth-logout.js";
// ... all other functions

This file is referenced by "main": "dist/index.js" in package.json.

Step 5: Configure the frontend

The frontend needs two changes:

1. HTTP interceptor — Cookies are not sent cross-origin by default, and the CSRF header must be present on every state-changing request. Example for Angular:

export const bffInterceptor: HttpInterceptorFn = (req, next) => {
  if (req.url.startsWith(environment.bffUrl)) {
    req = req.clone({
      withCredentials: true,
      setHeaders: { "X-Requested-With": "XMLHttpRequest" },
    });
  }
  return next(req);
};

2. Environment config — Point to /api in production (same origin, served by Azure SWA) and http://localhost:7071/api in development (Azure Functions local runtime).

Step 6: Configure local development

Use concurrently to run the frontend dev server and BFF together:

{
  "start": "concurrently \"ng serve\" \"npm run start:bff\"",
  "start:bff": "cd bff && npm start"
}

Step 7: Deploy to Azure Static Web Apps

Read references/deployment.md for the full deployment guide including GitHub Actions workflow config and environment variable setup.

Step 8: Verify environment variables on Azure SWA

After the user has deployed, ask them for their SWA app name and verify that all required environment variables are set. Do NOT set secrets — the user must run the az staticwebapp appsettings set command themselves since it involves credentials. Instead:

1. Ask the user to run the set command from references/deployment.md with their actual values
2. Once they confirm, verify by running:

   az staticwebapp appsettings list --name <swa-name> --query "[].name" -o tsv
   

3. Check that all six required variables are present: SESSION_SECRET, KEYCLOAK_URL, KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET, BACKEND_API_URL, ALLOWED_ORIGIN
4. If any are missing, tell the user which ones and provide the exact az command to set them

Critical pitfalls to avoid

These are real bugs encountered during development and deployment. Each one cost significant debugging time:

Azure SWA strips Set-Cookie headers

Azure SWA silently drops Set-Cookie headers from managed function responses. Use the cookies: Cookie[] property on HttpResponseInit instead of setting headers manually. This is the single most painful bug in the entire BFF setup because the login appears to succeed (200 response with correct body) but no cookie is set.

Azure SWA URL-encodes cookie values

@hapi/iron sealed tokens contain * characters (e.g., Fe26.2**...). Azure SWA encodes these to %2A. When the browser sends the cookie back, unseal() fails on the encoded string. Always decodeURIComponent() the cookie value before unsealing, with a try/catch fallback for already-decoded values.

CORS headers on error responses

When a CSRF check or session validation fails, the error response still needs CORS headers. Without them, the browser blocks the error response entirely and the frontend gets an opaque network error instead of a useful 401/403. Always spread corsHeaders into error responses.

ESM configuration

jose (used for JWT decoding) is ESM-only. The BFF must have "type": "module" in package.json. All local imports need .js extensions (e.g., import { foo } from './session.js').

Azure Functions route conflicts

Two Azure Functions cannot share the same route, even with different HTTP methods. If you need GET and POST on /entries, use a single function file that handles both methods.

The api_location in GitHub Actions

The Azure SWA GitHub Actions workflow needs api_location: "bff" to deploy the managed functions. If left empty, the BFF code is silently not deployed.

@types/hapi__iron version

The @types/hapi__iron package version ^6.0.6 does not exist on npm. Use ^6.0.1.

CSRF triggers CORS preflight

The X-Requested-With custom header triggers a CORS preflight (OPTIONS) request. Every endpoint that accepts state-changing requests must also accept OPTIONS and return proper CORS headers.

Adding new proxy endpoints

When adding a new proxied resource, follow this checklist:

1. Create bff/src/functions/proxy-<name>.ts
2. Handle OPTIONS preflight first
3. Check CSRF for state-changing methods (POST, PUT, DELETE)
4. Include CORS headers on ALL responses (success AND error)
5. Call proxyToBackend() with the backend path
6. Register the function with app.http() including OPTIONS in methods
7. Import the file in bff/src/index.ts
8. Build and test locally before deploying

Environment variables

For local development, set these in bff/local.settings.json (gitignored). For production, set them as Azure SWA Application Settings via az staticwebapp appsettings set.