vibesonic/docs/external-auth.md

External authentication

VibeSonic supports optional Navidrome-style externalized authentication: a trusted reverse proxy authenticates the browser user (via whatever mechanism it likes — OIDC, SAML, HTTP Basic Auth, a VPN identity, ...) and asserts that identity to VibeSonic via an HTTP header. VibeSonic never implements OIDC or talks to an identity provider itself — the proxy handles authentication, VibeSonic handles users and authorization.

Configuration

Variable	Default	Description
VIBESONIC_EXTAUTH_ENABLED	false	Enable external authentication
VIBESONIC_EXTAUTH_TRUSTED_SOURCES	(none)	Comma-separated list of IPv4/IPv6 CIDRs (or bare IPs) that are trusted to assert identity, e.g. 127.0.0.1/32,10.0.0.5/32
VIBESONIC_EXTAUTH_USER_HEADER	Remote-User	Header name carrying the authenticated username
VIBESONIC_EXTAUTH_LOGOUT_URL	(none)	Optional URL to send users to on logout (e.g. the proxy's own logout endpoint), instead of VibeSonic's local /login
VIBESONIC_EXTAUTH_AUTO_CREATE_USERS	true	Automatically create a VibeSonic user the first time a trusted identity is seen

The critical security property

The identity header is only trusted when the actual TCP connection peer address matches a configured trusted CIDR. This check (internal/auth/extauth.go) reads http.Request.RemoteAddr — the real socket peer — never a header.

Headers like X-Forwarded-For, X-Real-IP, or Forwarded are never consulted to decide whether the peer is trusted. Those headers are attacker-controlled: any client can set them to anything. If VibeSonic trusted them, an arbitrary internet client could add X-Forwarded-For: 127.0.0.1 and a Remote-User: admin header to its own direct request and be treated as an authenticated administrator.

This is why VIBESONIC_EXTAUTH_TRUSTED_SOURCES has no default — not 0.0.0.0/0, not ::/0, not RFC1918 ranges. External auth trusts nothing until you explicitly name a network (typically 127.0.0.1/32 for a proxy on the same host, or the proxy's specific address on a Docker bridge network).

See internal/auth/extauth_test.go for the regression tests covering this, including a test that a spoofed X-Forwarded-For/X-Real-IP/ Forwarded header from an untrusted peer is ignored entirely.

How it resolves to a user

A trusted identity resolves to an ordinary VibeSonic user (with external_auth = 1), never a separate "external user" type. If VIBESONIC_EXTAUTH_AUTO_CREATE_USERS=true and no user with that username exists yet, one is created with no local password. If a user with that username already exists (created locally or by a previous external login), it's reused.

Interaction with native auth

External auth and native session/password login coexist: the Authenticate middleware tries the session cookie first, then falls back to the trusted-proxy header. A user can still log in with a local password on VibeSonic's own /login page even when external auth is enabled, unless their account has no password hash set (auto-created external users start this way).

In later phases, /rest/* (the native Subsonic API) will authenticate exclusively via Subsonic's own token/API-key scheme and must never be affected by external auth's browser-cookie flow.