Running Solid behind a reverse proxy

Need: Running Solid alongside other services on a single port

If you want to run multiple services on a single port 443 of a machine, you will need a reverse proxy (such as NGINX) to route on HTTP level between different back-end services.

One of Solid's authentication mechanisms is WebID-TLS: the client sends its client certificate during the TLS handshake. However, by default, this requires the client to set up a TLS connection directly with the Solid server: if the TLS handshake is performed by an intermediary, the Solid server cannot see the client certificate.

Solution 1: Run Solid on a different port

When running Solid on a different port than the reverse proxy, we can bypass that proxy.

The drawbacks are uglier URLs (such as https://example.org:1234/), and possibly firewall problems (if only ports 80 and 443 are allowed).

Solution 2: Have the reverse proxy forward the client certificate through an HTTP header

2.1 Nginx

Second, you need to set up the reverse proxy such that it forwards the client certificate through an HTTP header of your choice. (We choose X-SSL-Cert here.) Here is an example configuration for NGINX:

server {
  # Place regular server and SSL configuration here

  # Ask for client certificate
  ssl_verify_client optional_no_ca;

  # Security: remove any client-set X-SSL-Cert headers
  # (not strictly necessary if they are overwritten below)
  proxy_set_header X-SSL-Cert "";

  # Redirect traffic to the internal Solid server
  proxy_pass http://127.0.0.1:5500$request_uri;
  proxy_set_header Host $http_host;
  proxy_pass_header Server;

  # Forward the client certificate in the X-SSL-Cert header
  proxy_set_header X-SSL-Cert $ssl_client_cert;
}

Then, you need to configure Solid such that it looks in the X-SSL-Cert header for the client certificate:

{
  …
  "webid": true,
  "auth": "tls",
  "certificateHeader": "X-SSL-Cert"
}

The internal Solid server can run over HTTP or HTTPS.

Security warning

The internal Solid server should not be publicly accessible. Otherwise, clients can present any certificate through the chosen header, as the certificate verification phase of the SSL handshake cannot be performed through the header. As an additional security measure, you might want to give your header a custom name other than X-SSL-Cert.