# How --trusted-origins Bypasses Authentication Origin Checks in code-server

> Learn how the --trusted-origins flag bypasses authentication origin checks in code-server by injecting a whitelist into origin-checking middleware to skip host-origin validation.

- Repository: [Coder/code-server](https://github.com/coder/code-server)
- Tags: internals
- Published: 2026-03-01

---

**The `--trusted-origins` flag injects a whitelist into the origin-checking middleware that allows specified origins to skip strict host-origin validation, returning early from the authentication check before a "Forbidden" error is thrown.**

The `coder/code-server` repository implements strict origin validation to protect its HTTP endpoints from cross-origin attacks. When deploying behind complex reverse proxies or accessing from multiple domains, administrators may need to bypass these checks for specific origins. This article explains how the `--trusted-origins` CLI argument interacts with the `authenticateOrigin` function in [`src/node/http.ts`](https://github.com/coder/code-server/blob/main/src/node/http.ts) to selectively disable origin authentication.

## How Origin Authentication Works

The origin verification system relies on two key components in [`src/node/http.ts`](https://github.com/coder/code-server/blob/main/src/node/http.ts): the `ensureOrigin` middleware and the `authenticateOrigin` validation function.

### The ensureOrigin Middleware

When a request arrives at the code-server HTTP interface, the `ensureOrigin` middleware intercepts it before processing continues. According to the source in [`src/node/http.ts`](https://github.com/coder/code-server/blob/main/src/node/http.ts), this middleware wraps the authentication logic in a try-catch block and invokes `authenticateOrigin(req)` to validate the request's origin header against expected values.

### Host Header Validation Logic

Under normal operation, `authenticateOrigin` extracts the `Origin` header from the incoming request and parses its host component. The function then performs a strict comparison between this origin host and the request's `Host` header, which represents the expected origin for correctly proxied deployments. If these values mismatch and no bypass mechanisms are active, the function throws a "Forbidden" error that blocks the request.

## How --trusted-origins Bypasses Authentication

The `--trusted-origins` flag modifies the validation logic by injecting a whitelist that is consulted before the strict host-origin comparison occurs.

### Trusted Origins Array Matching

The CLI flag is defined in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) with the configuration `"trusted-origins": { type: "string[]", description: "Disables authenticate origin check for trusted origin. Useful if not able to access reverse proxy configuration." }`. When code-server starts, this array is parsed into `req.args["trusted-origins"]` and becomes available to the authentication middleware.

Inside `authenticateOrigin` in [`src/node/http.ts`](https://github.com/coder/code-server/blob/main/src/node/http.ts), the logic retrieves this array with `const trustedOrigins = req.args["trusted-origins"] || [];`. Before performing the strict host-origin validation, the function checks: `if (trustedOrigins.includes(origin) || trustedOrigins.includes("*")) { return; }`. If the incoming origin matches any entry in this array, the function returns early, effectively bypassing the authentication origin check and allowing the request to proceed.

### Wildcard Support for All Origins

The implementation specifically supports the wildcard string `"*"` as a trusted origin value. When present in the array, this wildcard matches any incoming origin, completely disabling origin verification for all requests. This configuration requires extreme caution as it removes all origin-based protection from the server's authentication layer.

## Configuration Examples

You can supply trusted origins through command-line arguments or configuration files depending on your deployment requirements.

### Command Line Usage

Pass specific domains as comma-separated values or as repeated flags:

```bash

# Allow requests from https://example.com without origin verification

code-server --trusted-origins example.com

# Disable origin verification for all origins (use with extreme caution)

code-server --trusted-origins "*"

```

### YAML Configuration File

Define the array in a configuration file for persistent settings:

```yaml
trusted-origins:
  - example.com
  - staging.myapp.io

```

Start the server with the config file:

```bash
code-server --config config.yaml

```

### Programmatic Request Behavior

Without the flag, a request from an untrusted origin would be blocked:

```javascript
// This request would normally receive a 403 Forbidden response
fetch('https://my-code-server.com/api', {
  method: 'GET',
  credentials: 'include',
  headers: {
    Origin: 'https://untrusted.com'
  }
})

```

When the server runs with `--trusted-origins untrusted.com`, the `authenticateOrigin` function recognizes the match and returns early, allowing the request to succeed without triggering the host-origin validation failure.

## Summary

- The `ensureOrigin` middleware in [`src/node/http.ts`](https://github.com/coder/code-server/blob/main/src/node/http.ts) calls `authenticateOrigin` to validate all incoming HTTP requests against their origin headers.
- Under normal operation, `authenticateOrigin` compares the request's `Origin` header host against the `Host` header, rejecting mismatches with a "Forbidden" error.
- The `--trusted-origins` flag, defined in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts), populates `req.args["trusted-origins"]` with an array of whitelisted domains.
- If the incoming origin matches any entry in the trusted array—or if the wildcard `"*"` is present—`authenticateOrigin` returns early and skips the strict host-origin validation.
- This mechanism provides a controlled bypass for reverse proxy configurations where the standard origin checks would otherwise block legitimate traffic.

## Frequently Asked Questions

### What is the difference between --trusted-origins and disabling authentication entirely?

The `--trusted-origins` flag specifically bypasses only the origin validation step within the authentication pipeline, whereas disabling authentication would remove all security checks including password verification and session validation. Origin checking ensures that requests originate from expected domains, while authentication verifies the user's identity. The flag relaxes the former without affecting the latter.

### Why would I need to use --trusted-origins instead of fixing my reverse proxy?

According to the source code description in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts), this flag is "Useful if not able to access reverse proxy configuration." Some deployment environments—such as managed hosting platforms or corporate networks with restricted infrastructure access—prevent administrators from modifying proxy headers like `X-Forwarded-Host`. In these scenarios, the origin header seen by code-server may not match the expected host value through no fault of the deployment architecture, necessitating a whitelist-based bypass.

### Is it safe to use the wildcard "*" with --trusted-origins?

Using `--trusted-origins "*"` disables origin verification for all incoming requests, which the source code comments and documentation indicate should be used with "extreme caution." This configuration removes protection against cross-site request forgery (CSRF) attacks that rely on malicious websites making authenticated requests to your code-server instance. Only deploy the wildcard in highly controlled network environments where other security layers, such as network segmentation or VPN requirements, mitigate the risk of unauthorized cross-origin requests.

### Where does the origin validation logic reside in the codebase?

The validation logic is implemented in [`src/node/http.ts`](https://github.com/coder/code-server/blob/main/src/node/http.ts) within the `authenticateOrigin` function, which is invoked by the `ensureOrigin` middleware. The CLI argument definition and parsing reside in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts), which populates `req.args["trusted-origins"]` that the HTTP layer consumes. These two files form the complete bypass mechanism from configuration to execution.