99 lines
3.6 KiB
Markdown
99 lines
3.6 KiB
Markdown
# Put ThothII behind Caddy
|
|
|
|
Choose exactly one authentication mode. Direct ThothII-managed OIDC and deprecated upstream
|
|
authentication are mutually exclusive proxy contracts; never combine their directives.
|
|
|
|
## Direct ThothII-managed OIDC
|
|
|
|
Use this mode when `auth.yaml` has `mode: oidc`. Caddy terminates TLS and proxies every request to
|
|
`frontend`; ThothII performs login, callback validation, session creation, and authorization.
|
|
Caddy must not apply `forward_auth` or another external authentication gateway.
|
|
|
|
The public `/api/auth/oidc/login` and `/api/auth/oidc/callback` paths pass unchanged through the
|
|
same proxy as the rest of `/api`. The configured `publicUrl` must match the browser origin.
|
|
|
|
```caddyfile
|
|
thoth.example.invalid {
|
|
reverse_proxy 127.0.0.1:8080 {
|
|
# No URI rewrite: OIDC login and callback paths reach frontend unchanged.
|
|
flush_interval -1
|
|
header_up Host {host}
|
|
header_up X-Forwarded-Proto https
|
|
header_up X-Forwarded-Host {host}
|
|
}
|
|
|
|
log {
|
|
output file /var/log/caddy/thoth-access.log
|
|
format json
|
|
}
|
|
}
|
|
```
|
|
|
|
After reload, run Workspace Validate for static validation, `tht auth check` for live,
|
|
non-interactive authentication diagnosis, and then Workspace Test for aggregate live validation.
|
|
|
|
## Deprecated upstream migration mode
|
|
|
|
Use this section only while the installation explicitly uses deprecated `upstream` mode. Do not
|
|
use it with `mode: oidc` or `mode: local`. Here an external authentication gateway owns login and
|
|
Caddy applies `forward_auth` before forwarding normalized private identity headers to `frontend`.
|
|
|
|
Forwarding identity headers alone does not authenticate a user. The authentication gateway returns
|
|
2xx only after validating its own credential or session. Clear browser-supplied public and trusted
|
|
headers before the subrequest, and map identity only from the successful auth response.
|
|
|
|
```caddyfile
|
|
thoth.example.invalid {
|
|
route {
|
|
request_header -X-Authenticated-User
|
|
request_header -X-Thoth-Principal-Issuer
|
|
request_header -X-Thoth-Principal-Subject
|
|
request_header -X-Thoth-Principal-Display-Name
|
|
request_header -X-Thoth-Is-Admin
|
|
request_header -X-Thoth-Trusted-Principal-Issuer
|
|
request_header -X-Thoth-Trusted-Principal-Subject
|
|
request_header -X-Thoth-Trusted-Principal-Display-Name
|
|
request_header -X-Thoth-Trusted-Is-Admin
|
|
|
|
forward_auth auth-gateway:4180 {
|
|
uri /verify
|
|
copy_headers {
|
|
X-Thoth-Principal-Issuer>X-Thoth-Trusted-Principal-Issuer
|
|
X-Thoth-Principal-Subject>X-Thoth-Trusted-Principal-Subject
|
|
X-Thoth-Principal-Display-Name>X-Thoth-Trusted-Principal-Display-Name
|
|
X-Thoth-Is-Admin>X-Thoth-Trusted-Is-Admin
|
|
}
|
|
}
|
|
|
|
reverse_proxy 127.0.0.1:8080 {
|
|
flush_interval -1
|
|
header_up Host {host}
|
|
header_up X-Forwarded-Proto https
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Trust boundary
|
|
|
|
Caddy is the only public listener and proxies only to loopback `frontend`, never directly to
|
|
`core`. Configure access logs to omit cookies, authorization data, query strings, and identity
|
|
headers. Keep Caddy keys and state outside ThothII source and operator directories.
|
|
|
|
## Validate and reload
|
|
|
|
Keep the public firewall closed while validating:
|
|
|
|
```sh
|
|
curl --fail http://127.0.0.1:8080/health
|
|
caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
|
|
sudo systemctl reload caddy
|
|
```
|
|
|
|
## Test authentication and SSE
|
|
|
|
For direct OIDC, verify the login path redirects to the configured provider, the callback reaches
|
|
ThothII unchanged, forged identity headers grant nothing, and SSE is unbuffered. For deprecated
|
|
upstream mode, additionally verify the external gateway rejects unauthenticated traffic and only
|
|
its 2xx response can create trusted identity headers.
|