OpenSEO Authentication Modes: How `cloudflare_access`, `local_noauth`, and `hosted` Work

OpenSEO supports three authentication modes—cloudflare_access (default for production), local_noauth (development-only), and hosted (self-hosted deployments)—all defined in src/lib/auth-mode.ts with helper utilities to detect and branch on the active mode.

The open-source OpenSEO application (from every-app/open-seo) provides flexible authentication to accommodate different deployment environments. Whether you're running in Cloudflare's edge network, developing locally, or self-hosting on your own infrastructure, the codebase uses a centralized configuration system to determine how users prove their identity.

The Three Authentication Modes in OpenSEO

The AUTH_MODES constant in src/lib/auth-mode.ts enumerates the three supported strategies:

Mode	Use Case
cloudflare_access	Production deployments using Cloudflare Access and your organization's identity provider
local_noauth	Local development with authentication completely disabled
hosted	Self-hosted deployments where you bring your own authentication strategy

cloudflare_access: Default Production Mode

This is the default authentication mode for all production-hosted deployments. When AUTH_MODE is unset or invalid, OpenSEO falls back to this mode.

Cloudflare Access integrates with corporate identity providers (IdPs) like Okta, Google Workspace, or Azure AD. The application trusts Cloudflare's JWT validation at the edge, simplifying authentication logic in the application layer.

local_noauth: Development-Only Bypass

Use this mode for rapid prototyping and local testing. It disables all authentication checks, allowing developers to start the application without configuring credentials or identity providers.

Warning: Never use local_noauth in production. The mode is intentionally restricted to development environments.

hosted: Self-Hosted Deployments

The hosted mode supports self-hosted installations where you operate OpenSEO on your own infrastructure. Unlike cloudflare_access, this mode expects the UI and backend to share the same AUTH_MODE value at build time.

When running in hosted mode, you must implement your own authentication layer—OpenSEO bypasses Cloudflare Access entirely and exposes hooks for custom auth strategies.

Helper Functions for Detecting the Active Mode

The src/lib/auth-mode.ts module exports three utility functions that the rest of the codebase uses to branch on authentication behavior:

• getAuthMode(value) – Parses a string (typically process.env.AUTH_MODE) and returns a valid mode, defaulting to cloudflare_access for unrecognized values
• isHostedAuthMode(value) – Returns true when the mode equals hosted
• isHostedClientAuthMode() – Returns true when the client-side build environment indicates a hosted deployment

These predicates appear throughout the codebase in src/server.ts, src/serverFunctions/workspace.ts, and route guards like src/routes/_auth.tsx.

Practical Code Examples

Detect and Branch on the Authentication Mode

// src/lib/auth-mode.ts utilities in action
import { getAuthMode, isHostedAuthMode } from "@/lib/auth-mode";

const mode = getAuthMode(process.env.AUTH_MODE);
console.log(`Running in ${mode} mode`);

if (isHostedAuthMode(mode)) {
  // Initialize custom auth provider for self-hosted deployment
  configureCustomAuth();
} else if (mode === "cloudflare_access") {
  // Verify Cloudflare Access JWT headers
  validateCloudflareJWT();
}

Client-Side Authentication UI

// Conditional UI rendering based on auth mode
import { isHostedClientAuthMode } from "@/lib/auth-mode";

if (isHostedClientAuthMode()) {
  // Render login form for custom auth provider
  return <CustomLoginForm />;
} else {
  // Show Cloudflare Access login button
  return <CloudflareAccessButton />;
}

Bypass Authentication in Development

// Development-only shortcut for local testing
import { getAuthMode } from "@/lib/auth-mode";

if (getAuthMode(process.env.AUTH_MODE) === "local_noauth") {
  // Treat all requests as authenticated admin
  request.user = { role: "admin", id: "dev-user" };
  return next();
}

Where Authentication Mode Logic Appears in OpenSEO

File	Responsibility
src/lib/auth-mode.ts	Central definitions, parsing logic, and helper predicates
src/server.ts	Runtime configuration based on AUTH_MODE environment variable
src/serverFunctions/workspace.ts	Workspace functions that branch authentication checks by mode
src/routes/_auth.tsx	UI routing decisions using isHostedClientAuthMode()

Summary

• OpenSEO's three authentication modes—cloudflare_access, local_noauth, and hosted—are defined in src/lib/auth-mode.ts
• getAuthMode(), isHostedAuthMode(), and isHostedClientAuthMode() provide the detection utilities used across the application
• cloudflare_access is the production default integrating with Cloudflare Access and corporate IdPs
• local_noauth provides credential-free development but must never be used in production
• hosted enables self-hosted deployments with custom authentication strategies

Frequently Asked Questions

How do I set the authentication mode in OpenSEO?

Set the AUTH_MODE environment variable to cloudflare_access, local_noauth, or hosted. If omitted or invalid, OpenSEO defaults to cloudflare_access via the getAuthMode() function in src/lib/auth-mode.ts.

Can I use local_noauth in production?

No. The local_noauth mode is designed exclusively for local development. Running it in production would leave your application completely unprotected, as this mode treats every request as authenticated without verification.

What authentication options exist for self-hosted OpenSEO?

Self-hosted deployments use the hosted mode, which bypasses Cloudflare Access entirely. You must implement your own authentication layer, as OpenSEO expects you to provide the identity verification strategy that matches your infrastructure.

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