ttyd auth headers and client certificates are different trust paths

ttyd shares a terminal over the web. Its documentation offers basic authentication, an authentication header for a reverse proxy, and client-certificate verification. Those options are often treated as interchangeable ways to add a login. They trust different components and fail in different ways.

The official ttyd command-line documentation describes --credential for basic authentication, --auth-header for a reverse proxy that handles authentication, and --ssl-ca for client certificate verification. The tool can also use --check-origin to validate the WebSocket origin. A secure deployment needs to choose the path that matches its network and identity architecture.

A large fingerprint surface

On 10 November 2026, ZoomEye count-only observations used sub_type=all, page 1, and page size 1. app="ttyd" returned 92,918 matches. title="ttyd" returned 122,959, and http.body="ttyd" returned 210,408.

The selected evidence is the ZoomEye application search for app="ttyd". The large count is not a count of unsafe terminals. It is a measure of how widely a terminal-over-web component appears in public data. Validate a representative sample and map it to ownership before drawing conclusions.

Basic authentication

Basic authentication sends a reusable username and password with each request. It must run over TLS. The credential is often placed in a reverse proxy or process configuration, so file permissions and process inspection matter. Rotate the password when an operator leaves, and do not share the same credential across unrelated hosts.

Basic authentication also does not provide a session-specific second factor. If the deployment needs MFA, place an identity-aware proxy in front of ttyd and ensure the backend is not reachable around it.

Auth headers require a trusted proxy

With --auth-header, ttyd accepts an HTTP header set by a reverse proxy. The proxy must authenticate the user, remove any client-supplied version of that header, and set the value after successful authentication. If the backend is directly reachable, an attacker may be able to send the header themselves.

Test the complete path:

  1. Send a request with the auth header directly to the backend. It should be rejected or unreachable.
  2. Send the same header through the proxy without a session. The proxy should strip or reject it.
  3. Authenticate through the proxy and confirm the expected user reaches the terminal.
  4. Remove the user from the proxy group and verify that a new connection is denied.

Use a private network or a service mesh policy to ensure the only route to the backend is the trusted proxy.

Client certificates

Client-certificate verification changes the trust anchor. The server checks a certificate against a configured CA. That can be stronger than a shared header, but it moves lifecycle work to certificate issuance, renewal, revocation, and device inventory. A revoked user whose certificate is still accepted by the CA remains able to connect.

If client certificates are used, record the issuing CA, the allowed subject or identity mapping, the revocation method, and the certificate lifetime. Test with an expired certificate, a certificate from another CA, and a revoked certificate. Do not treat a certificate as proof of authorization unless the application or proxy maps it to a specific principal and role.

Origin and session controls

Enable origin checking when the deployment supports it. A terminal WebSocket should not accept a cross-site connection from an unrelated page. Restrict the allowed origins to the actual administrative host. Combine origin checks with network restrictions and authentication.

Set connection limits and idle timeouts. A terminal session can stay open longer than a normal web session. Define whether closing the browser ends the shell, and whether the proxy or ttyd enforces the timeout. Avoid a shared session that one operator can leave open for another.

Inventory the terminal path

Use the application matches to find candidate services, then verify the direct backend route, proxy authentication, certificate configuration, and reachable host authority. Record the service account and the commands it can run.

The 92,918 fingerprint matches make terminal exposure a material inventory problem. The useful control is not a blanket count. It is proof that each terminal has one trusted authentication path, no bypass route, and a session lifecycle that matches the administrative risk.

References