Auth Proxy

The -H, --auth-header command-line flag will configure ttyd to let a HTTP reverse proxy handle authentication.

Running ttyd

Security NOTICE: Since the auth proxy feature will make ttyd trust any request with none empty X-WEBAUTH-USER header value, you should always start ttyd on a unix domain socket. If you really want ttyd to listen on an IP or interface, do not forget to block direct requests to ttyd that you do not trust with your firewall (for example: iptables on linux).

ttyd -i /tmp/ttyd.sock -H X-WEBAUTH-USER bash

Running Proxy Server

sample configurations for apache and nginx proxy with basic auth.

• Apache

  <VirtualHost *:80>
      <Proxy *>
          AuthType Basic
          AuthName ttyd
          AuthBasicProvider file
          AuthUserFile /etc/apache2/ttyd_htpasswd
          Require valid-user
  
          RewriteEngine On
          RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS]
          RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e"
      </Proxy>
  
      RequestHeader unset Authorization
  
      ProxyRequests Off
      ProxyPass /ws unix:/tmp/ttyd.sock|ws://localhost/ws
      ProxyPass / unix:/tmp/ttyd.sock|http://localhost/
      ProxyPassReverse / unix:/tmp/ttyd.sock|http://localhost/
  </VirtualHost>

• Nginx

  location / {
      auth_basic "ttyd";
      auth_basic_user_file "/etc/apache2/ttyd_htpasswd";
      proxy_set_header X-WEBAUTH-USER $remote_user;
      proxy_set_header Authorization "";
  
      proxy_http_version 1.1;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      
      proxy_pass http://unix:/tmp/ttyd.sock;
  }

You may also need to allow the web server's user to access ttyd's unix domain socket file (typically www-user on linux):

sudo chown www-data:www-data /tmp/ttyd.sock

Proxying multiple ttyd sessions

It is possible to use Apache to host multiple ttyd instances with the following configuration.

    <VirtualHost *:80>
        <Proxy *>
            AuthType Basic
            AuthName ttyd
            AuthBasicProvider file
            AuthUserFile /etc/apache2/ttyd_htpasswd
            Require valid-user

            RewriteEngine On
            RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS]
            RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e"
        </Proxy>

        RequestHeader unset Authorization

        ProxyRequests Off
        ProxyPass /ttyd/1/ws unix:/tmp/ttyd1.sock|ws://localhost:8001/ws
        ProxyPass /ttyd/1/ unix:/tmp/ttyd1.sock|http://localhost8001/
        ProxyPassReverse ttyd/1/ unix:/tmp/ttyd1.sock|http://localhost:8001/

        ProxyPass /ttyd/2/ws unix:/tmp/ttyd2.sock|ws://localhost:8002/ws
        ProxyPass /ttyd/2/ unix:/tmp/ttyd2.sock|http://localhost8002/
        ProxyPassReverse ttyd/2/ unix:/tmp/ttyd2.sock|http://localhost:8002/
    </VirtualHost>

OIDC authenticating proxy

The mod_auth_openidc can protect a running instance of ttyd with OpenID Connect. This will authenticate and authorize users before giving service. mod_auth_openidc can be set up to authenticate with Google or servers like Keycloak. The snippet below utilizes Keycloak; the preferred_username claim is used to restrict access of ttyd to a single user.

  RewriteEngine On

  LogLevel info auth_openidc:info

  OIDCProviderMetadataURL https://idp.example.com/realms/EXAMPLE/.well-known/openid-configuration
  OIDCClientID <client-id>
  OIDCClientSecret <client-secret>

  # OIDCRedirectURI is a vanity URL that must point to a path protected by 
  # but must NOT point to any content
  OIDCRedirectURI https://example.com/ttyd/callback
  OIDCCryptoPassphrase <passphrase>
  OIDCOAuthRemoteUserClaim preferred_username

  <Location /ttyd/callback>
    AuthType openid-connect
    Require claim preferred_username:example_user
  </Location>

  #ttyd
  ProxyPass /ttyd/             unix:/tmp/ttyd1.sock|http://localhost:8001/
  ProxyPassReverse /ttyd/      unix:/tmp/ttyd1.sock|http://localhost:8001/

  RewriteCond %{HTTP:Upgrade} =websocket [NC]
  RewriteRule /ttyd/(.*)           unix:/tmp/ttyd1.sock|ws://localhost:8001/$1 [P,L]

  RewriteCond %{HTTP:Upgrade} !=websocket [NC]
  RewriteRule /ttyd/(.*)           unix:/tmp/ttyd1.sock|ws://localhost:8001/$1 [P,L]