Implement BFF OAuth2 Proxy

[eoaksnes]

Describe Problem

The application requires secure authentication for the SPA frontend to communicate with the FastAPI backend API. Direct OAuth2 flows from the browser (implicit flow or authorization code with PKCE stored in browser) expose tokens to XSS attacks and require complex token management in the frontend. Without a Backend-for-Frontend (BFF) pattern, the frontend must handle token refresh, storage, and secure transmission, increasing attack surface and complexity.

Suggest Solution

Implement a BFF OAuth2 proxy using oauth2-proxy  with the following architecture:

1. Deploy oauth2-proxy as an intermediary between the SPA and backend API
   • Configure OIDC authentication with Microsoft Entra ID (Azure AD)
   • Use PKCE (code_challenge_method: S256) for secure authorization code flow
   • Enable Redis-backed session storage for horizontal scalability
2. Configure Nginx reverse proxy with auth_request directive
   • Route /oauth2/* paths directly to oauth2-proxy
   • Enforce authentication on /api/* routes (return 401 if unauthenticated)
   • Redirect unauthenticated users to sign-in for all other routes
3. Token injection via headers
   • Inject Authorization: Bearer <id_token> header for API requests
   • Forward X-Auth-Request-Access-Token for additional validation
4. Secure cookie configuration
   • cookie_secure: true, cookie_httponly: true, cookie_samesite: lax
   • 15-minute token refresh interval, 1-hour session expiry
   • CSRF protection with per-request tokens
5. Backend JWT validation in FastAPI
   • Validate tokens against Azure AD JWKS endpoint
   • Extract user claims (oid, name, email, roles) for authorization

Additional Details

• OAuth 2 Proxy

[eoaksnes]

BFF Architecture with OAuth2-Proxy

This document describes the Backend For Frontend (BFF) pattern implementation using OAuth2-Proxy and NGINX. This architecture ensures secure authentication where the frontend SPA never directly handles tokens.

Overview

The BFF pattern places a server-side component between the browser and backend API to handle authentication. In this implementation:

• OAuth2-Proxy manages authentication sessions and token handling
• NGINX acts as the entry point, enforcing auth via auth_request
• Redis stores encrypted session data
• Frontend uses cookie-based sessions (no tokens in JavaScript)

flowchart LR
    subgraph Browser
        SPA["React SPA"]
    end
    
    subgraph BFF["BFF Layer"]
        NGINX["NGINX<br/>:8080"]
        OAuth2["OAuth2-Proxy<br/>:8081"]
        Redis["Redis<br/>Session Store"]
    end
    
    subgraph Backend
        API["API Server<br/>:5000"]
    end
    
    subgraph IdP["Identity Provider"]
        EntraID["Microsoft Entra ID"]
    end
    
    SPA -->|"1. Request /api/*"| NGINX
    NGINX -->|"2. auth_request"| OAuth2
    OAuth2 <-->|"Session lookup"| Redis
    OAuth2 -->|"3. Validate/Refresh"| EntraID
    NGINX -->|"4. Forward + tokens"| API
    API -->|"5. Response"| NGINX
    NGINX -->|"6. Response"| SPA

Loading

Authentication Flow

sequenceDiagram
    participant Browser
    participant NGINX
    participant OAuth2-Proxy
    participant Redis
    participant EntraID
    participant API

    Browser->>NGINX: GET /api/data
    NGINX->>OAuth2-Proxy: auth_request /oauth2/auth
    OAuth2-Proxy->>Redis: Lookup session cookie
    
    alt No valid session
        OAuth2-Proxy-->>NGINX: 401 Unauthorized
        NGINX-->>Browser: Redirect to /oauth2/sign_in
        Browser->>OAuth2-Proxy: GET /oauth2/sign_in
        OAuth2-Proxy-->>Browser: Redirect to EntraID
        Browser->>EntraID: Authorization request
        EntraID-->>Browser: Redirect with code
        Browser->>OAuth2-Proxy: GET /oauth2/callback?code=...
        OAuth2-Proxy->>EntraID: Exchange code for tokens
        EntraID-->>OAuth2-Proxy: Access + ID tokens
        OAuth2-Proxy->>Redis: Store session
        OAuth2-Proxy-->>Browser: Set cookie, redirect to original URL
    end
    
    alt Valid session
        OAuth2-Proxy-->>NGINX: 200 OK + token headers
        NGINX->>API: GET /data<br/>Authorization: Bearer <id_token><br/>X-Forwarded-Access-Token: <access_token>
        API-->>NGINX: Response
        NGINX-->>Browser: Response
    end

Loading

Project Structure

├── docker-compose.yml           # Service orchestration
├── web/
│   ├── nginx/
│   │   ├── sites-available/
│   │   │   └── default.conf     # Main NGINX config
│   │   └── config/
│   │       ├── oauth2.conf          # OAuth2 proxy settings
│   │       ├── oauth2.auth.conf     # Auth subrequest config
│   │       ├── oauth2.redirect.conf # Token forwarding config
│   │       └── proxy.conf           # Proxy headers
│   ├── oauth2/
│   │   ├── Dockerfile           # OAuth2-Proxy container
│   │   ├── oauth2-proxy.yaml    # Alpha config (OIDC provider)
│   │   ├── oauth2-proxy.toml    # Main config (cookies, Redis)
│   │   └── entrypoint.sh        # Secret injection script
│   └── src/
│       ├── api/generated/core/
│       │   └── OpenAPI.ts       # API client config
│       └── setupFetchInterceptors.tsx  # 401 handling
├── redis/
│   └── Dockerfile               # Redis for session storage
└── secrets/
    ├── OAUTH2_PROXY_COOKIE_SECRET.txt
    └── REDIS_PASSWORD.txt

Implementation Guide

1. Docker Compose Services

services:
  nginx:
    build:
      context: ./web
    ports:
      - "80:8080"
    links:
      - api
      - oauth2

  oauth2:
    build: ./web/oauth2
    depends_on:
      - cookie-cache
    secrets:
      - oauth2-client-secret
      - redis-password
      - oauth2-cookie-secret
    environment:
      CLIENT_SECRET_FILE: '/run/secrets/oauth2-client-secret'
      OAUTH2_PROXY_REDIS_PASSWORD_FILE: '/run/secrets/redis-password'
      OAUTH2_PROXY_COOKIE_SECRET_FILE: '/run/secrets/oauth2-cookie-secret'
      OAUTH_CLIENT_ID: your-client-id
      OAUTH2_PROXY_REDIRECT_URL: http://localhost/oauth2/callback

  cookie-cache:
    image: redis:alpine
    volumes:
      - cookie_cache_data:/data
    secrets:
      - redis-password

  api:
    build: ./api
    environment:
      VALID_OAUTH_AUDIENCES: your-oauth2-client-id

volumes:
  cookie_cache_data:

secrets:
  oauth2-client-secret:
    file: secrets/OAUTH2_CLIENT_SECRET.txt
  redis-password:
    file: secrets/REDIS_PASSWORD.txt
  oauth2-cookie-secret:
    file: secrets/OAUTH2_PROXY_COOKIE_SECRET.txt

2. OAuth2-Proxy Configuration

oauth2-proxy.yaml (OIDC Provider Config)

injectResponseHeaders:
  - name: X-Auth-Request-Access-Token
    values:
      - claimSource:
          claim: access_token
  - name: Authorization
    values:
      - claimSource:
          claim: id_token
          prefix: "Bearer "

providers:
  - provider: oidc
    id: Microsoft Entra ID
    clientID: ${OAUTH_CLIENT_ID}
    clientSecretFile: ${CLIENT_SECRET_FILE}
    oidcConfig:
      audienceClaims:
        - aud
      emailClaim: email
      insecureAllowUnverifiedEmail: true
      issuerURL: "https://login.microsoftonline.com/${TENANT_ID}/v2.0"
    scope: openid profile offline_access email ${API_SCOPE}
    code_challenge_method: S256

server:
  BindAddress: 0.0.0.0:8081

upstreamConfig:
  upstreams:
    - id: nginx
      path: /
      uri: http://nginx:8080/

oauth2-proxy.toml (Cookie & Session Config)

# Email domains allowed to authenticate
email_domains = ["your-domain.com"]

# Required for running behind a reverse proxy
reverse_proxy = true

# Skip the "Sign in with..." button
skip_provider_button = true

# Cookie security settings
cookie_samesite = "lax"
cookie_secure = true          # Set to false for local HTTP development
cookie_httponly = true        # Prevents JavaScript access
cookie_refresh = "15m"        # Refresh tokens before expiry
cookie_expire = "1h"          # Session duration
cookie_csrf_per_request = true

# Redis session storage
session_store_type = "redis"
redis_connection_url = "redis://cookie-cache:6379"

# API routes return 401 instead of redirect
api_routes = ["^/api/.*"]

3. NGINX Configuration

default.conf (Main Server Config)

server {
    listen 8080;
    server_name localhost;

    # OAuth2-Proxy endpoints
    location /oauth2 {
        proxy_pass http://oauth2:8081;
        include /etc/nginx/config/oauth2.conf;
    }

    # Auth subrequest endpoint (internal)
    location = /oauth2/auth {
        proxy_pass http://oauth2:8081;
        include /etc/nginx/config/oauth2.auth.conf;
    }

    # API routes - enforce auth, return 401 on failure
    location /api/ {
        proxy_pass http://api:5000/;
        
        include /etc/nginx/config/proxy.conf;
        include /etc/nginx/config/oauth2.redirect.conf;
        
        error_page 401 = @api_unauthorized;
    }

    location @api_unauthorized {
        return 401;
    }

    # Frontend - enforce auth, redirect to login on failure
    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
        
        include /etc/nginx/config/oauth2.redirect.conf;
        error_page 401 = /oauth2/sign_in;
    }
}

oauth2.redirect.conf (Token Injection)

# Trigger auth check
auth_request /oauth2/auth;

# Extract and forward tokens from OAuth2-Proxy response headers
auth_request_set $token         $upstream_http_authorization;
proxy_set_header Authorization  $token;

auth_request_set $access_token              $upstream_http_x_auth_request_access_token;
proxy_set_header X-Forwarded-Access-Token   $access_token;

oauth2.auth.conf (Auth Subrequest)

proxy_set_header Host             $host;
proxy_set_header X-Real-IP        $remote_addr;
proxy_set_header X-Scheme         $scheme;
# Auth request doesn't need body
proxy_set_header Content-Length   "";
proxy_pass_request_body           off;

oauth2.conf (OAuth2 Proxy Headers)

proxy_set_header Host                    $host;
proxy_set_header X-Real-IP               $remote_addr;
proxy_set_header X-Scheme                $scheme;
proxy_set_header X-Auth-Request-Redirect $request_uri;

4. Frontend Integration

API Client Configuration

Configure your API client to include credentials (cookies) with every request:

export const OpenAPI: OpenAPIConfig = {
    BASE: '',           // Use relative paths - NGINX routes to API
    CREDENTIALS: 'include',  // Send cookies with requests
    // No TOKEN property - authentication is cookie-based
};

Session Expiry Handling

Intercept 401 responses and prompt users to re-authenticate:

export const SetupFetchInterceptors = ({ children }: { children: ReactNode }) => {
  const [expired, setExpired] = useState(false)
  const loginTabRef = useRef<Window | null>(null)

  useEffect(() => {
    const originalFetch = window.fetch.bind(window)

    window.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
      const mergedInit: RequestInit = { ...init, redirect: 'manual' }

      const response = await originalFetch(input, mergedInit)
      if (response.status === 401) {
        setExpired(true)
      }
      return response
    }
  }, [])

  const openLoginTab = () => {
    // Open login in new tab, redirect to success page after
    window.open('/oauth2/start?rd=/auth-success', '_blank')
  }

  return (
    <>
      <Dialog open={expired}>
        <Dialog.Title>Session expired</Dialog.Title>
        <p>Your session has expired. Click Login to re-authenticate.</p>
        <Button onClick={openLoginTab}>Login</Button>
      </Dialog>
      {children}
    </>
  )
}

5. Backend JWT Validation

The API receives tokens in headers and validates them:

import jwt
from cachetools import TTLCache, cached
from fastapi import Security
from fastapi.security import OAuth2AuthorizationCodeBearer

oauth2_scheme = OAuth2AuthorizationCodeBearer(
    authorizationUrl=config.OAUTH_AUTH_ENDPOINT,
    tokenUrl=config.OAUTH_TOKEN_ENDPOINT,
    auto_error=False,
)

@cached(cache=TTLCache(maxsize=32, ttl=86400))  # Cache JWKS for 24h
def get_JWK_client() -> jwt.PyJWKClient:
    oid_conf = httpx.get(config.OAUTH_WELL_KNOWN).json()
    return jwt.PyJWKClient(oid_conf["jwks_uri"])

def auth_with_jwt(jwt_token: str = Security(oauth2_scheme)) -> User:
    if not jwt_token:
        raise UnauthorizedException
    
    jwt_client = get_JWK_client()
    payload = jwt.decode(
        jwt_token,
        jwt_client.get_signing_key_from_jwt(jwt_token).key,
        algorithms=["RS256"],
        audience=config.VALID_OAUTH_AUDIENCES,
    )
    
    return User(
        user_id=payload["oid"],
        name=payload["name"],
        email=payload["preferred_username"],
        roles=payload.get("roles", []),
    )

Security Benefits

Feature	Implementation	Benefit
No tokens in browser JS	OAuth2-Proxy stores tokens server-side	Prevents XSS token theft
HttpOnly cookies	cookie_httponly = true	JavaScript cannot access session
Secure cookies	cookie_secure = true	Cookies only sent over HTTPS
SameSite cookies	cookie_samesite = "lax"	CSRF protection
Encrypted sessions	OAUTH2_PROXY_COOKIE_SECRET	Session data encrypted at rest
Automatic refresh	cookie_refresh = "15m"	Tokens refreshed before expiry
PKCE	code_challenge_method: S256	Prevents authorization code interception
API 401 responses	api_routes = ["^/api/.*"]	APIs return 401, not redirect

Required Secrets

Secret	Purpose	Generation
OAUTH2_CLIENT_SECRET	OAuth2 app client secret	From identity provider
REDIS_PASSWORD	Redis authentication	openssl rand -hex 32
OAUTH2_PROXY_COOKIE_SECRET	Cookie encryption	openssl rand -base64 32 | tr -- '+/' '-_'

Azure App Registration Setup

1. Create App Registration in Microsoft Entra ID
2. Add Redirect URI: https://your-domain/oauth2/callback
3. Configure permissions:
   • openid, profile, email, offline_access (delegated)
   • Your API scope (e.g., api://your-api/access)
4. Create client secret and store in secrets file
5. Note the Client ID for OAUTH_CLIENT_ID environment variable

Testing Locally

1. Generate secrets:

   mkdir -p secrets
   openssl rand -hex 32 > secrets/REDIS_PASSWORD.txt
   openssl rand -base64 32 | tr -- '+/' '-_' > secrets/OAUTH2_PROXY_COOKIE_SECRET.txt
   # Add your Azure client secret
   echo "your-client-secret" > secrets/OAUTH2_CLIENT_SECRET.txt

2. Set cookie_secure to false for HTTP:

   cookie_secure = false  # Only for local development!

3. Start services:

   docker compose up

4. Access at http://localhost