feat: add feature flags for nonce validation and strict authorize returnTo

Add two feature flags to control security features with safe defaults:

**Feature Flag 1: enable_nonce_validation (default: false)**
- Controls CSRF nonce validation in OAuth flows
- When disabled: Nonce is generated but not validated (future compatibility)
- When enabled: Full CSRF protection with nonce and origin validation
- Nonce cookies are always generated and cleared for consistency

**Feature Flag 2: enable_strict_authorize_return_to (default: false)**
- Controls returnTo validation strictness for /api/authorize endpoint
- When disabled: Falls back to login validation (broader patterns)
- When enabled: Uses strict authorize validation (limited to specific paths)
- /api/login always uses login validation regardless of flag

**Implementation Details:**
- Always generate nonce for consistency and future compatibility
- Only validate nonce when feature flag is enabled
- Always clear nonce cookies regardless of validation state
- Authorize endpoint checks flag and falls back gracefully
- Comprehensive logging for debugging and monitoring

**Backward Compatibility:**
- Default false ensures no breaking changes
- Gradual rollout possible via feature flag configuration
- Existing authentication flows continue to work
- Safe fallback behavior when flags are disabled

Co-authored-by: Ona <[email protected]>

Author: iQQBot

components/server/src/auth/authenticator.ts

@@ -21,6 +21,7 @@ import { HostContextProvider } from "./host-context-provider";
 import { SignInJWT } from "./jwt";
 import { NonceService } from "./nonce-service";
 import { ensureUrlHasFragment } from "./fragment-utils";
+import { getFeatureFlagEnableNonceValidation, getFeatureFlagEnableStrictAuthorizeReturnTo } from "../util/featureflags";
 
 /**
  * Common validation logic for returnTo URLs.
@@ -173,32 +174,35 @@ export class Authenticator {
                     return;
                 }
 
-                // Validate nonce for CSRF protection
-                const stateNonce = flowState.nonce;
-                const cookieNonce = this.nonceService.getNonceFromCookie(req);
-
-                if (!this.nonceService.validateNonce(stateNonce, cookieNonce)) {
-                    log.error(`CSRF protection: Nonce validation failed`, {
-                        url: req.url,
-                        hasStateNonce: !!stateNonce,
-                        hasCookieNonce: !!cookieNonce,
-                    });
-                    res.status(403).send("Authentication failed");
-                    return;
+                // Validate nonce for CSRF protection (if feature flag is enabled)
+                const isNonceValidationEnabled = await getFeatureFlagEnableNonceValidation();
+                if (isNonceValidationEnabled) {
+                    const stateNonce = flowState.nonce;
+                    const cookieNonce = this.nonceService.getNonceFromCookie(req);
+
+                    if (!this.nonceService.validateNonce(stateNonce, cookieNonce)) {
+                        log.error(`CSRF protection: Nonce validation failed`, {
+                            url: req.url,
+                            hasStateNonce: !!stateNonce,
+                            hasCookieNonce: !!cookieNonce,
+                        });
+                        res.status(403).send("Authentication failed");
+                        return;
+                    }
+
+                    // Validate origin for additional CSRF protection
+                    if (!this.nonceService.validateOrigin(req)) {
+                        log.error(`CSRF protection: Origin validation failed`, {
+                            url: req.url,
+                            origin: req.get("Origin"),
+                            referer: req.get("Referer"),
+                        });
+                        res.status(403).send("Invalid request");
+                        return;
+                    }
                 }
 
-                // Validate origin for additional CSRF protection
-                if (!this.nonceService.validateOrigin(req)) {
-                    log.error(`CSRF protection: Origin validation failed`, {
-                        url: req.url,
-                        origin: req.get("Origin"),
-                        referer: req.get("Referer"),
-                    });
-                    res.status(403).send("Invalid request");
-                    return;
-                }
-
-                // Clear the nonce cookie after successful validation
+                // Always clear the nonce cookie
                 this.nonceService.clearNonceCookie(res);
 
                 const hostContext = this.hostContextProvider.get(host);
@@ -213,7 +217,7 @@ export class Authenticator {
                 await hostContext.authProvider.callback(req, res, next);
             } catch (error) {
                 log.error(`Failed to handle callback.`, error, { url: req.url });
-                // Clear nonce cookie on error as well
+                // Always clear nonce cookie on error
                 this.nonceService.clearNonceCookie(res);
             }
         } else {
@@ -315,7 +319,7 @@ export class Authenticator {
             return;
         }
 
-        // Generate nonce for CSRF protection
+        // Always generate nonce for CSRF protection (validation controlled by feature flag)
         const nonce = this.nonceService.generateNonce();
         this.nonceService.setNonceCookie(res, nonce);
 
@@ -391,8 +395,17 @@ export class Authenticator {
         }
 
         // Validate returnTo URL against allowlist for authorize API
-        if (!validateAuthorizeReturnToUrl(returnToParam, this.config.hostUrl)) {
-            log.warn(`Invalid returnTo URL rejected for authorize: ${returnToParam}`, { "authorize-flow": true });
+        const isStrictAuthorizeValidationEnabled = await getFeatureFlagEnableStrictAuthorizeReturnTo();
+        const isValidReturnTo = isStrictAuthorizeValidationEnabled
+            ? validateAuthorizeReturnToUrl(returnToParam, this.config.hostUrl)
+            : validateLoginReturnToUrl(returnToParam, this.config.hostUrl);
+
+        if (!isValidReturnTo) {
+            const validationType = isStrictAuthorizeValidationEnabled ? "strict authorize" : "login fallback";
+            log.warn(`Invalid returnTo URL rejected for authorize (${validationType}): ${returnToParam}`, {
+                "authorize-flow": true,
+                strictValidation: isStrictAuthorizeValidationEnabled,
+            });
             res.redirect(this.getSorryUrl(`Invalid return URL.`));
             return;
         }
@@ -459,7 +472,7 @@ export class Authenticator {
         // authorize Gitpod
         log.info(`(doAuthorize) wanted scopes (${override ? "overriding" : "merging"}): ${wantedScopes.join(",")}`);
 
-        // Generate nonce for CSRF protection
+        // Always generate nonce for CSRF protection (validation controlled by feature flag)
         const nonce = this.nonceService.generateNonce();
         this.nonceService.setNonceCookie(res, nonce);
 

components/server/src/auth/return-to-validation.spec.ts

@@ -88,6 +88,58 @@ describe("ReturnTo URL Validation", () => {
                 expect(result).to.equal(false, `Should reject www.gitpod.io non-root: ${url}`);
             });
         });
+
+        describe("Feature Flag Integration", () => {
+            it("should document nonce validation feature flag behavior", () => {
+                // Feature flag: enable_nonce_validation (default: false)
+                // When enabled: Full CSRF protection with nonce validation
+                // When disabled: Nonce is generated but not validated (for future compatibility)
+
+                // This test documents the expected behavior:
+                // 1. Nonce is always generated and stored in cookie
+                // 2. Nonce is always included in JWT state
+                // 3. Nonce validation only occurs when feature flag is enabled
+                // 4. Cookie is always cleared after callback processing
+
+                expect(true).to.equal(true); // Documentation test
+            });
+
+            it("should document strict authorize returnTo validation feature flag behavior", () => {
+                // Feature flag: enable_strict_authorize_return_to (default: false)
+                // When enabled: Uses validateAuthorizeReturnToUrl (strict patterns)
+                // When disabled: Falls back to validateLoginReturnToUrl (broader patterns)
+
+                // This test documents the expected behavior:
+                // 1. /api/authorize endpoint checks the feature flag
+                // 2. If enabled: Only allows complete-auth, root, /new, /quickstart
+                // 3. If disabled: Falls back to login validation (broader patterns)
+                // 4. /api/login endpoint always uses login validation
+
+                expect(true).to.equal(true); // Documentation test
+            });
+
+            it("should show difference between strict and fallback validation", () => {
+                const testUrls = [
+                    { url: "https://gitpod.io/workspaces", strictAllowed: false, fallbackAllowed: true },
+                    { url: "https://gitpod.io/settings", strictAllowed: false, fallbackAllowed: true },
+                    { url: "https://gitpod.io/new", strictAllowed: true, fallbackAllowed: true },
+                    { url: "https://gitpod.io/quickstart", strictAllowed: true, fallbackAllowed: true },
+                    {
+                        url: "https://gitpod.io/complete-auth?message=success",
+                        strictAllowed: true,
+                        fallbackAllowed: true,
+                    },
+                ];
+
+                testUrls.forEach(({ url, strictAllowed, fallbackAllowed }) => {
+                    const strictResult = validateAuthorizeReturnToUrl(url, hostUrl);
+                    const fallbackResult = validateLoginReturnToUrl(url, hostUrl);
+
+                    expect(strictResult).to.equal(strictAllowed, `Strict validation failed for: ${url}`);
+                    expect(fallbackResult).to.equal(fallbackAllowed, `Fallback validation failed for: ${url}`);
+                });
+            });
+        });
     });
 
     describe("validateAuthorizeReturnToUrl", () => {

components/server/src/util/featureflags.ts

@@ -17,3 +17,19 @@ export async function getFeatureFlagEnableContextEnvVarValidation(userId: string
         user: { id: userId },
     });
 }
+
+/**
+ * Feature flag for enabling nonce validation in OAuth flows.
+ * Default: false (disabled)
+ */
+export async function getFeatureFlagEnableNonceValidation(): Promise<boolean> {
+    return getExperimentsClientForBackend().getValueAsync("enable_nonce_validation", false, {});
+}
+
+/**
+ * Feature flag for enabling strict returnTo validation for /api/authorize endpoint.
+ * Default: false (disabled, falls back to login validation)
+ */
+export async function getFeatureFlagEnableStrictAuthorizeReturnTo(): Promise<boolean> {
+    return getExperimentsClientForBackend().getValueAsync("enable_strict_authorize_return_to", false, {});
+}