ttyd auth headers and client certificates are different trust paths

ttyd offers multiple methods to authenticate users accessing its terminal-over-web component: basic authentication, authentication headers for reverse proxies, and client-certificate verification. These methods are often viewed as interchangeable ways to secure access, but they trust different components, leading to varied failure modes.

The official ttyd documentation differentiates between the --credential flag for basic authentication, --auth-header for reverse proxies handling authentication, and --ssl-ca for client certificate verification. Another option, --check-origin, validates the WebSocket origin. Implementing the appropriate method depends on the network and identity architecture of the deployment.

ZoomEye's application search for "ttyd" revealed 92,918 instances, emphasizing the prevalence of this terminal-over-web component in public data. To validate a representative sample and map it to ownership, a thorough analysis is necessary before drawing conclusions.

For basic authentication, a reusable username and password are sent with each request, requiring TLS for secure transmission. The credential often resides in a reverse proxy or process configuration, making file permissions and process inspection crucial. Password rotation and avoiding credential sharing across unrelated hosts are recommended practices.

However, basic authentication lacks a second-factor mechanism for session security. To address this, placing an identity-aware proxy in front of ttyd and ensuring the backend is inaccessible through it can provide multi-factor authentication.

Auth headers rely on a trusted reverse proxy to authenticate users. The proxy must authenticate the user, clear any client-supplied version of the header, and set the authenticated value after successful authentication. If the backend is directly reachable, an attacker might intercept and send the header themselves, bypassing security measures.

Testing the complete path involves sending requests with the auth header directly to the backend, which should be rejected or unreachable, and through the proxy without a session, which should strip or reject the header. Successful authentication through the proxy confirms the expected user reaches the terminal, and revoking user access from the proxy group denies new connections.

Client certificates introduce a different trust anchor, requiring the server to check the certificate against a configured Certificate Authority (CA). While this method can be stronger than shared headers, it shifts lifecycle responsibilities to certificate issuance, renewal, revocation, and device inventory management. Revoked certificates that are still accepted by the CA allow unauthorized access.

Recording the issuing CA, allowed subject or identity mapping, revocation method, and certificate lifetime is essential. Testing with expired, unknown CA-issued, and revoked certificates ensures robust verification.

Enabling origin checks restricts WebSocket connections to the actual administrative host, preventing cross-site requests. Combining origin checks with network restrictions and authentication strengthens security. Setting connection limits and idle timeouts is also crucial, as terminal sessions may remain open longer than typical web sessions. Defining whether closing the browser ends the shell and whether the proxy or ttyd enforces timeouts helps manage session lifecycles effectively.

Inventorying the terminal path by examining application matches, verifying direct backend routes, proxy authentication, certificate configurations, and reachable host authorities is vital. Recording the service account and the commands it can run provides a comprehensive view of the terminal's capabilities. With 92,918 fingerprint matches, ensuring each terminal has a unique trusted authentication path, no bypass routes, and a session lifecycle aligned with administrative risk is a material inventory problem that demands attention.