25 Secure Sockets (SSL)

SSL Configuration

If your RStudio Workbench is running on a public network then configuring it to use SSL (Secure Sockets Layer) encryption is strongly recommended. You can do this via the ssl-enabled setting along with related settings that specify the location of your SSL certificate and key. For example:

# /etc/rstudio/rserver.conf
ssl-enabled=1
ssl-certificate=/var/certs/your_domain_name.crt
ssl-certificate-key=/var/certs/your_domain_name.key

The .crt file should be encoded in the PEM format; that is, the first line should read -----BEGIN CERTIFICATE-----, and the contents should be base64-encoded data. If your certificate is in another format, such as DER or PKCS, use the openssl command-line tool to convert it to PEM. For example:

openssl x509 -inform DER -outform PEM -text -in your_domain_name.der -out your_domain_name.crt

It’s important when installing the certificate .crt file that you concatenate together any intermediate certificates (i.e. the generic one from your certificate authority) with the certificate associated with your domain name. For example you could use a shell command of this form to concatenate the CA intermediate certificate to your domain name’s certificate:

$ cat certificate-authority.crt >> your_domain_name.crt

The resulting file should then be specified in the ssl-certificate option.

It’s also important to ensure that the file permissions on your SSL certificate key are as restrictive as possible so it can’t be read by ordinary users. The file should typically be owned by the root user and be set as owner readable and writable. For example:

$ sudo chmod 600 /var/certs/your_domain_name.key

SSL Protocols

By default RStudio Workbench supports the TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 protocols for SSL. The list of supported protocols can configured via the ssl-protocols option. For example, to use only the TLSv1.1 and TLSv1.2 protocols you would use:

# /etc/rstudio/rserver.conf
ssl-protocols=TLSv1.1 TLSv1.2

The list of supported protocols is space delimited (as illustrated above). Valid protocol values are: SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3.

Note that not all protocols may be available on your system; TLS 1.1 and 1.2 require OpenSSL 1.0.1, and TLS 1.3 requires OpenSSL 1.1.1 built with TLS 1.3 support.

SSL Ports

When RStudio Workbench is configured to use SSL the default behavior with respect to ports is:

SSL is bound to port 443 (enabling access using the standard https protocol within the browser)
The server also listens on port 80 and redirects all requests to port 443 (allowing users to specify the domain without the https protocol and be automatically redirected to the secure port)

However, if SSL is bound to another port (using the www-port option) then the automatic redirect behavior is not enabled. It’s also possible to disable automatic SSL redirects entirely using the ssl-redirect-http option as follows:

# /etc/rstudio/rserver.conf
ssl-redirect-http=0

Note that changes to the configuration will not take effect until the server is restarted.

Strict Transport Security

When SSL is enabled, RStudio Workbench sends an HTTP Strict Transport Security (HSTS) header, Strict-Transport-Security, by default on outbound responses. This header tells the browser to forbid all HTTP connections to the domain for a period of time.

RStudio Workbench sets this period of time to 1 day (84600 seconds) by default, because if HTTPS issues arise it can be difficult to address them when the browser is locked to HTTPS because of HSTS. Once you are confident that your HTTPS setup is correct, you can increase the period by specifying the desired number of seconds in the ssl-hsts-max-age option. For example, to lock browsers to HTTPS for one year:

# /etc/rstudio/rserver.conf
ssl-hsts-max-age=31536000

If all subdomains of the server on which RStudio Workbench is hosted support HSTS, you can extend HSTS protection to them as well with the ssl-hsts-include-subdomains option. This doesn’t happen by default since RStudio Workbench does not know what other services it’s sharing a domain with, but it’s a recommended security best practice, so you should turn it on if you can.

# /etc/rstudio/rserver.conf
ssl-hsts-include-subdomains=1

Finally, we do not recommend disabling HSTS, but if you need to, you can do so by setting ssl-hsts=0.