65 lines
3.3 KiB
Markdown
65 lines
3.3 KiB
Markdown
# 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.
|