Published: October 8, 2025
Last updated: August 24, 2026
Suggest an edit

Authenticate based on HTTP headers – strictly designed to be used behind a reverse proxy.

Configuration

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

auth:
  methods:
    proxy:
      enabled: true
      header: "X-Forwarded-User"  # or "Remote-User"
      # Optional role/group headers (v2.1.0+):
      # groupsClaim: "x-cosmos-role"  # HTTP header name for group/role value
      # userGroups: ["2", "1"]        # allow-list; omit to allow all
      # adminGroup: "2"               # group value that grants admin
      # userIdentifier: ""
      # disableVerifyTLS: false   # testing only
      # logoutRedirectUrl: ""

Options

OptionDescription
enabledEnable proxy authentication
headerRequired. Header whose value is trusted as the username (must sit behind a trusted proxy)
adminGroupv2.1.0+. Group/role header value that grants admin privileges
userGroupsv2.1.0+. If set, only users whose group/role header value is in this list may log in
groupsClaimv2.1.0+. HTTP header name for the user’s group/role (required when userGroups or adminGroup is set)
userIdentifierField to use as username when not using the raw header value in composite setups
disableVerifyTLSDisable TLS verification for any outbound calls (testing only)
logoutRedirectUrlOptional URL to redirect after logout

Sources for proxy users

Proxy users are auto-created on first successful header auth. Source access follows the callout at the top of this page. From v2.1.0+, proxy auth syncs group/role header values into the access-control GroupMap (write-through to the database), same as OIDC / LDAP / JWT.

Example Use Cases

  • Corporate SSO via proxy
  • Kubernetes ingress authentication
  • Nginx auth_request module
  • Traefik ForwardAuth
  • Cosmos Cloud auth proxy with role headers

Cosmos Cloud Example (v2.1.0+)

Cosmos Cloud sends a username header and a numeric role header (0 = guest, 1 = user, 2 = admin):

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

auth:
  methods:
    password:
      enabled: false
    proxy:
      enabled: true
      header: "X-Cosmos-User"
      groupsClaim: "x-cosmos-role"
      userGroups:
        - "2"
        - "1"
      adminGroup: "2"

Expected behavior:

  • Role 0 (guest): login denied, user not created
  • Role 1 (user): regular user access
  • Role 2 (admin): regular access plus admin privileges

Traefik Example

YAML 
1
2
3
4
5
6

http:
  middlewares:
    auth:
      forwardAuth:
        address: "https://auth.example.com/verify"
        trustForwardHeader: true

Nginx Example

TEXT 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

map $remote_addr $uuid {
    default "demo-${remote_addr}";
}

server {
    listen 80;
    server_name localhost 127.0.0.1;

    location / {
        proxy_set_header X-Username $uuid;
        add_header X-Forwarded-User $uuid;
        proxy_pass http://filebrowser:8080/subpath;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

FileBrowser config:

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# v2.0.0+
http:
  trustProxyHeaders: true

auth:
  methods:
    proxy:
      enabled: true
      header: "X-Forwarded-User"
    password:
      enabled: false
YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# v1.4.x–v1.5.x
http:
  trustedHeaders:
    - X-Forwarded-Proto
    - X-Forwarded-Host
    - X-Forwarded-For
    - X-Real-IP

auth:
  methods:
    proxy:
      enabled: true
      header: "X-Forwarded-User"
    password:
      enabled: false

Next Steps