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

> Explore OpenSEO authentication modes: cloudflare_access, local_noauth, and hosted. Understand how each mode works for production, development, and self-hosted setups.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server.ts), [`src/serverFunctions/workspace.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/workspace.ts), and route guards like [`src/routes/_auth.tsx`](https://github.com/every-app/open-seo/blob/main/src/routes/_auth.tsx).

## Practical Code Examples

### Detect and Branch on the Authentication Mode

```typescript
// 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

```typescript
// 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

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/src/lib/auth-mode.ts) | Central definitions, parsing logic, and helper predicates |
| [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) | Runtime configuration based on `AUTH_MODE` environment variable |
| [`src/serverFunctions/workspace.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/workspace.ts) | Workspace functions that branch authentication checks by mode |
| [`src/routes/_auth.tsx`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.