Cloudflare Worker

Migration Proxy - Cloudflare Workers-based traffic router for gradual SSO backend migration

A production-ready proxy service that enables zero-downtime migration from an old Single Sign-On (SSO) authentication backend to a new one. This worker intelligently routes authentication requests based on user preference while maintaining backward compatibility.

Overview

The SSO Worker acts as an intelligent traffic router during the migration from a legacy SSO backend to a new one. It provides:

• Gradual user migration - Users can opt-in to the new backend via query parameter
• Seamless fallback - Easy rollback to old backend if issues arise
• Zero downtime - No service interruption during migration

Important: This is a temporary migration tool. Once all users are migrated to the new backend and the old backend is decommissioned, this worker will be sunset.

Architecture

The worker sits between clients and the SSO backends, routing traffic based on a backend_selector cookie:

Client Request
     |
     v
SSO Worker (Cloudflare Edge)
     |
     +---> Cookie = "new" OR ?new query param ---> NEW Backend
     |
     +---> No cookie OR ?old query param --------> OLD Backend
     |

Features

1. Cookie-Based Backend Selection

• Cookie name: backend_selector
• Default: Routes to old backend
• When backend_selector=new: Routes to new backend
• Secure, HttpOnly, SameSite=Lax cookies with 1-year expiration

2. Query Parameter Backend Switching

• ?new - Sets backend selector cookie and redirects (307) to new backend
• ?old - Deletes backend selector cookie and redirects (307) to old backend
• Preserves other query parameters during redirect

3. Full HTTP Proxy

• Preserves HTTP method (GET, POST, PUT, DELETE, etc.)
• Forwards all headers and request body
• Maintains query parameters
• Handles trailing slashes correctly

Environments

Development

• Old Backend: https://old-backend.example.com
• New Backend: https://new-backend.example.com
• Usage: Local testing and development

Staging

• Old Backend: Configure OLD_BACKEND_URL in wrangler.jsonc
• New Backend: Configure NEW_BACKEND_URL in wrangler.jsonc
• Usage: Pre-production testing with real backend instances

Production

• Old Backend: Configure OLD_BACKEND_URL in wrangler.jsonc
• New Backend: Configure NEW_BACKEND_URL in wrangler.jsonc
• Usage: Live production traffic

Deployment

Prerequisites

• Wrangler CLI installed
• Cloudflare account with Workers enabled
• Node.js 18+ and npm

Deploy to Specific Environment

# Deploy to production (default)
npm run deploy

# Deploy to staging
npx wrangler deploy --env staging

# Deploy to development
npx wrangler deploy --env dev

Verify Deployment

# Check deployment status
npx wrangler deployments list

# View logs
npx wrangler tail

Development

Setup

# Install dependencies
npm install

# Generate TypeScript types from wrangler config
npm run cf-typegen

Local Development

# Start local development server (dev environment)
npm start
# or
npm run dev

# The worker will be available at http://localhost:8787

Testing

# Run all tests
npm test

# Watch mode (re-run tests on file changes)
npm run test:watch

# Generate coverage report
npm run test:coverage

The test suite includes 40+ test cases covering:

• Query parameter redirects (?new/?old)
• Cookie-based routing
• UserFromToken parallel requests
• Edge cases and error handling

Linting

# Type check
npm run lint

Code Formatting

This project uses Prettier for code formatting:

• 140 character line width
• Tabs for indentation
• Single quotes

Usage

For End Users

Opt-in to New Backend

Visit any SSO URL with the ?new query parameter:

https://your-sso-worker.workers.dev/some-endpoint?new

This sets a cookie and redirects you to the new backend. All subsequent requests will use the new backend.

Opt-out (Return to Old Backend)

Visit any SSO URL with the ?old query parameter:

https://your-sso-worker.workers.dev/some-endpoint?old

This removes the cookie and redirects you to the old backend.

For Developers

Testing Backend Switching

# Test redirect to new backend
curl -i "http://localhost:8787/SsoAuthApi/Login?new"

# Observe Set-Cookie header in response
# Follow redirect to new backend

# Test redirect to old backend
curl -i "http://localhost:8787/SsoAuthApi/Login?old"

Migration Timeline

Current Status: Production deployment active

Migration Phases:

1. Phase 1 (Current): Worker deployed, both backends operational
2. Phase 2: Gradual user opt-in to new backend via communications
3. Phase 3: Monitor error rates and user feedback
4. Phase 4: Force-migrate remaining users to new backend
5. Phase 5: Decommission old backend
6. Phase 6: Sunset this worker, direct traffic to new backend

Sunset Plan: Once all users are migrated and the old backend is decommissioned, this worker will be removed and traffic will be routed directly to the new backend.

Technical Details

Key Constants

• COOKIE_NAME = 'backend_selector'

Security Features

• Proper cookie parsing (no substring matching vulnerability)
• Request timeout protection with AbortController
• Secure cookie attributes (HttpOnly, Secure, SameSite)
• No credential leakage between backends

Error Handling

• Preserves error responses from backends