Single sign-on in plain words
Single sign-on means you log in once and every app trusts that login. The apps do not hold your password. A separate login server holds it.
The idea in four steps
- You open
status.example.com. Your browser has no session. - Caddy, the reverse proxy, asks the login server: “Is this request from a
logged-in user?” This call is
forward_auth. - The login server says no. Caddy sends your browser to the login page.
- You log in. The login server sets a cookie. From now on the answer is yes, and Caddy forwards your request to the app.
The app never sees a login. It only sees requests that already passed.
Why one cookie covers many apps
The cookie belongs to the parent domain, example.com. A browser sends it to
every subdomain, so status.example.com and rss.example.com both receive
it. One login, one cookie, many apps.
This also sets a limit. Every app under that domain shares the cookie. An app that you do not trust should not live on a subdomain of it.
What the app can learn
When the login server says yes, Caddy copies a few headers into the request:
Remote-User, Remote-Email, Remote-Groups, and Remote-Name. Some apps
accept these headers as proof of identity. They create the account on first
visit and skip their own login.
That trust is dangerous. A header is only text. If anyone can reach the app
without going through the proxy, they can write Remote-User: admin
themselves. Two rules follow:
- Let the app listen only on the private Docker network, never on a public port.
- Test the app with a forged header before you rely on it. I found one app that accepted the forged header from any source.
When headers are the wrong tool
Some apps cannot use headers. They support OpenID Connect (OIDC) instead. In OIDC, the app sends you to the login server, gets a signed token back, and checks the signature. No header is trusted. Authelia can act as the OIDC provider, so the same login covers these apps too.
What cannot sit behind a login page
A phone app cannot click through a web login page. DNS clients cannot either. So some paths stay outside single sign-on and keep their own authentication: the DNS-over-HTTPS endpoint, the password manager API, and the music server.
I treat this as a list that I write down, not as an accident. Every open path has a reason and its own lock.
Where to go next
- One VPS, one login has my real Caddy and Authelia config, with the traps I hit.
- What a reverse proxy does covers the piece that asks the question.