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

> Discover OpenSEO's authentication modes: Cloudflare JWT, local development, and hosted OAuth. Secure your applications with flexible validation and authorization options.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: authentication-modes
- Published: 2026-09-09

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server.ts)** demonstrates how OpenSEO branches middleware logic based on the resolved authentication mode:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.