Authentication Modes Supported by OpenSEO: Cloudflare, Local, and Hosted

OpenSEO supports three distinct authentication modes—cloudflare_access for Cloudflare JWT validation, local_noauth for unrestricted development, and hosted for internal OAuth provider integration—that determine how the platform validates and authorizes incoming requests.

The every-app/open-seo repository implements a flexible, environment-aware authentication architecture that adapts to different deployment contexts. Understanding the authentication modes supported by OpenSEO is essential for securely configuring the platform whether you are deploying to Cloudflare's edge network, running local integration tests, or managing a self-hosted production instance.

The Three Authentication Modes

OpenSEO defines its authentication strategies in the AUTH_MODES constant located in src/lib/auth-mode.ts. The platform recognizes three distinct modes that govern how requests are validated at runtime.

cloudflare_access

cloudflare_access serves as the default authentication mode for deployments running on Cloudflare. In this configuration, OpenSEO validates requests using Cloudflare Access-based JWTs, leveraging Cloudflare's identity-aware proxy to authenticate users before they reach the application. This mode provides enterprise-grade security without requiring custom authentication logic within the application layer.

local_noauth

local_noauth is a development-only mode that completely disables authentication, allowing unrestricted local testing. This mode is ideal for rapid iteration during development or when running automated integration tests where managing OAuth flows would create unnecessary friction. Never use this mode in production environments.

hosted

hosted mode is designed for self-hosted deployments where the UI and server must share the same AUTH_MODE environment variable. When active, authentication is performed via the internal OAuth provider, making this mode suitable for organizations running OpenSEO on their own infrastructure with custom identity providers.

Core Implementation in src/lib/auth-mode.ts

The authentication mode logic is centralized in src/lib/auth-mode.ts, which exports the AUTH_MODES constant and several utility functions for mode detection.

According to the OpenSEO source code, the AUTH_MODES constant explicitly declares the three supported values (lines 3–7), while helper functions like getAuthMode, isHostedAuthMode, and isHostedClientAuthMode (lines 15–33) provide type-safe ways to interpret the AUTH_MODE environment variable and determine which authentication strategy to apply.

// src/lib/auth-mode.ts – Resolve the current mode from an env variable
import { getAuthMode, isHostedAuthMode } from "@/lib/auth-mode";

const mode = getAuthMode(process.env.AUTH_MODE);
if (isHostedAuthMode(mode)) {
  // Perform hosted-specific OAuth handling
}

Runtime Resolution in src/server.ts

The central request dispatcher in src/server.ts determines the active authentication mode at runtime by calling getAuthMode(env.AUTH_MODE) at line 47. This value then dictates request routing logic, determining whether to process OAuth flows, handle self-hosted MCP endpoints, or bypass authentication entirely for local development (lines 47–57 and 71–77).

The server uses the resolved mode to branch between three distinct execution paths:

1. Cloudflare Access or Local No-Auth: Routes matching /mcp with cloudflare_access or local_noauth modes are handled by the self-hosted MCP request handler
2. Hosted OAuth: Routes in hosted mode are forwarded to the internal openSeoOAuthProvider
3. Standard Application: All other requests fall through to the main application handler

Mode-Based Request Routing

The following implementation from src/server.ts demonstrates how OpenSEO branches middleware logic based on the resolved authentication mode:

// src/server.ts – Example of mode-based routing
import { getAuthMode, isHostedAuthMode } from "@/lib/auth-mode";

export async function handleFetch(request: Request, env: Env) {
  const authMode = getAuthMode(env.AUTH_MODE);

  // Cloudflare Access / Local No-Auth MCP route
  if ((authMode === "cloudflare_access" || authMode === "local_noauth")
      && pathname === "/mcp") {
    return handleSelfHostedOpenSeoMcpRequest(request, authMode, env);
  }

  // Hosted OAuth provider
  if (isHostedAuthMode(authMode)) {
    return openSeoOAuthProvider.fetch(request, env);
  }

  // Fallback to the application handler
  return appFetch(request);
}

This pattern ensures that authentication logic remains decoupled from business logic, with each mode receiving appropriate security handling without affecting the core application flow.

Key Files in the Authentication System

Understanding the authentication architecture requires familiarity with these specific source files:

• src/lib/auth-mode.ts – Defines the AUTH_MODES constant and exports utility functions (getAuthMode, isHostedAuthMode, isHostedClientAuthMode) that interpret the AUTH_MODE environment variable
• src/server.ts – Central request dispatcher that branches behavior based on the active authentication mode via getAuthMode(env.AUTH_MODE) at line 47
• src/server/mcp/transport.ts – Handles self-hosted MCP requests, using the authMode value to permit or reject accesses based on the current security context
• src/server/features/google/selfHostedOAuth.ts – Demonstrates how hosted mode integrates with the internal OAuth provider for Google service authentication

These files collectively implement the authentication strategy that allows OpenSEO to operate securely across Cloudflare, self-hosted, and development environments.

Summary

• OpenSEO defines three authentication modes in src/lib/auth-mode.ts: cloudflare_access (Cloudflare JWT), local_noauth (development only), and hosted (internal OAuth)
• The getAuthMode function resolves the active mode from the AUTH_MODE environment variable at runtime
• src/server.ts uses the resolved mode to route requests between Cloudflare Access validation, self-hosted MCP handling, or the internal OAuth provider
• local_noauth disables all authentication and should only be used in local development environments
• hosted mode requires the UI and server to share identical AUTH_MODE values for consistent authentication state

Frequently Asked Questions

Which authentication mode should I use for local development?

Use local_noauth for local development and testing. This mode disables authentication entirely, allowing you to test API endpoints and MCP functionality without configuring OAuth credentials or Cloudflare Access. Never deploy local_noauth to production, as it leaves your instance completely unsecured.

How does OpenSEO validate requests in Cloudflare deployments?

In cloudflare_access mode, OpenSEO relies on Cloudflare Access-based JWTs to validate requests. The platform expects Cloudflare's edge network to authenticate users via your configured identity provider and pass valid JWTs to the application. OpenSEO then validates these tokens without implementing a separate authentication layer.

What is the difference between hosted and cloudflare_access modes?

cloudflare_access delegates authentication to Cloudflare's infrastructure and validates JWTs at the edge, making it ideal for serverless deployments. hosted mode uses an internal OAuth provider (openSeoOAuthProvider) that you control, making it suitable for self-hosted deployments where you manage your own authentication infrastructure and the UI must share authentication state with the server.

Where do I configure the authentication mode in OpenSEO?

Set the AUTH_MODE environment variable to cloudflare_access, local_noauth, or hosted. The src/server.ts file reads this variable at startup via getAuthMode(env.AUTH_MODE) (line 47) to determine which authentication strategy to enforce for the duration of the process lifecycle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}