Backchannel Permission Upgrade Flow

This document details Phase 1 of our edge-native authentication and authorization architecture. In this phase, user identity is centralized at the Central Auth Edge, while the ownership of authorization rules and permissions remains delegated to individual downstream application databases.

To bridge this gap without sacrificing sub-millisecond, database-free token validation on subsequent requests, we implement a Backchannel Permission Upgrade pattern.

1. Core Architectural Goals

• Identity Centralization: Single Sign-On (SSO) and credential management run entirely on the Cloudflare Edge.
• Delegated Authorization: Downstream application servers maintain complete, localized control over user roles, database schema joins, and fine-grained permissions.
• Zero-Lookup Requests: Once the login handshake is complete, all subsequent API calls are validated locally in-memory (0ms database overhead) using standard JWT signature verification and bitmask math.
• Forward Compatibility: The design allows a seamless, zero-downtime migration path to Phase 2 (fully centralized edge permissions) without changing client login behaviors or client-side storage mechanics.

2. System Components & Actors

The architecture consists of three core actors:

• Client Browser: The web browser requesting access.
• Downstream Application Server (with Integration Library): Running our integration library. It has its own relational database containing specific business logic tables, user records, and local permission maps.
• Central Auth Edge Server (Cloudflare Worker): The gatekeeper of identities. It manages credential verification, app registrations, API token hashes, and Ed25519 token signing.

3. Sequence Flow

4. Handshake & Upgrade Lifecycle

Step 3.1: Redirect Generation

When an unauthenticated user attempts to access a protected route on a downstream application:

1. The application’s integration library intercepts the request.
2. It generates a cryptographically random, short-lived string called a state parameter to prevent Cross-Site Request Forgery (CSRF).
3. It redirects the user to the Central Auth Server with query parameters:

https://auth.domain.com/authorize?client_id=app_1&redirect_uri=https://app1.com/callback&state=xyz123

Step 3.2: Edge Authentication & Temporary Code

1. The user inputs their credentials on the central login portal.
2. The Cloudflare Worker validates the credentials against Cloudflare D1.
3. Instead of issuing a long-lived JWT directly to the browser, the Worker generates an ephemeral, single-use Authorization Code (valid for 60 seconds) and stores it temporarily.
4. The Worker redirects the browser back to the downstream application’s registered callback URL:

https://app1.com/callback?code=temp_code_abc999&state=xyz123

Step 3.3: Backchannel Permission Lookup & Upgrade Request

1. The application server intercepts the callback, validates the state parameter, and retrieves the temporary code.
2. The application server’s integration library reads the temporary token or user identifier associated with the code.
3. The Permission Lookup: The library queries its own local application database to fetch the user’s local permission bitmask mapping:

   SELECT IFNULL(SUM(local_permission_id), 0) as user_bitmask 
   FROM user_permissions 
   WHERE user_id = ?;

4. The Upgrade Call: The application server bypasses the browser entirely and fires a secure backend POST request to the Central Auth Server’s private endpoint: /api/tokens/upgrade. The request carries the Application Auth Key (acting as a bearer secret) and the user’s computed local bitmask in the payload:

   {
     "client_id": "app_1",
     "user_id": "user_998877",
     "inject_permissions": 43
   }

Step 3.4: Verification, Signing & Cookie Application

1. The Central Auth Worker validates the client_id and verifies that the provided Application Auth Key matches the hashed credential registered in Cloudflare D1.
2. It generates a final JWT payload containing:

   {
     "sub": "user_998877",
     "aud": "app_1",
     "permissions": 43,
     "exp": 1782345600
   }

3. The Worker signs this payload using the secure Ed25519 private key and sends the upgraded JWT back to the application server.
4. The integration library receives this upgraded token and sets it as an encrypted, HttpOnly, Secure, SameSite=Strict browser cookie.