Secure Sockets (SSL)
SSL configuration
If your Posit 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.crtIt’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.crtThe 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 When using an existing load balancing environment and enabling or disabling SSL, the load balancing cluster will need to be reset. See Defining nodes for more information.
Secure session communication
For local sessions, not using the Job Launcher, data is transmitted to sessions securely from Posit Workbench to the session using unix domain sockets.
On the other hand, when Posit Workbench connects to a Job Launcher session, where sessions can live on a separate host, it uses SSL connections to encrypt traffic over the network by default. Posit Workbench auto-provisions the required SSL certificates, creating one for each job. These certificates are accessible only to Posit Workbench and the session user, and are stored temporarily in a scratch area inside of the user’s home directory on the session node. The server only trusts this certificate when making the connection. Using these auto-provisioned certificates eliminates the need to manage per user SSL certificates, while still offering secure connections.
Although session SSL is enabled by default, it’s important for data security to explicitly configure SSL for Posit Workbench, and the Job Launcher when it’s enabled.
Auto-generated certificates are easy to use but may not adhere to security policies that require use of certificates explicitly created using a different process. In that case, it is also possible to manually create your own session SSL certificates, and configure Posit Workbench to use them. To enable this option, set the path names for the session to use to find the private key.pem and public cert.pem files. These files must be accessible to the session user and can make user of environment variables such as USER and HOME. For example:
# /etc/rstudio/rserver.conf
session-ssl-cert=/home/${USER}/cert.pem
session-ssl-cert-key=/home/${USER}/key.pemPosit Workbench will verify the certificate’s common name, and/or alternative subject names as usual. When sessions may run on multiple hosts, such as when using load balancing, Slurm, or Kubernetes, a wildcard ip-address pattern, or DNS pattern will be required in the certificate so that one will be valid for all of the session hosts.
When creating your own certificates for session SSL, be aware that the private key for these certificates is available to the session user. They are not maintained with the level of secrecy required for a public website, accessed over a public domain. Be careful not to create session certificates using public host names or ip-addresses that could give session users the ability to impersonate or monitor traffic for a public website using the same host name.
You can disable certificate verification for session SSL connections for debugging or development purposes with this setting:
# /etc/rstudio/rserver.conf
session-ssl-verify-certs=0It is strongly recommended to leave certificate verification enabled when using Posit Workbench in production.
If you are manually provisioning certificates using an authority not trusted by Openssl, configure it with:
# /etc/rstudio/rserver.conf
session-ssl-cert-authority=/etc/ssl/certs/sessionRootCert.pemThis path is accessed only by the Posit Workbench server, not the session, and cannot use environment variables from the session user’s environment.
To eliminate the overhead involved with session SSL for a private, secure network, disable this feature by setting session-ssl-enabled=0 in rserver.conf:
# /etc/rstudio/rserver.conf
session-ssl-enabled=0It is strongly recommended to leave session SSL enabled unless using a secure, private network. Otherwise, session information is transmitted without encryption and susceptible to misuse by anyone with access to the network traffic.
SSL protocols
By default Posit 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.2The 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 Posit 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=0Note that changes to the configuration will not take effect until the server is restarted.
Strict Transport Security
When SSL is enabled, Posit 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.
Posit 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=31536000If all subdomains of the server on which Posit 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 Posit 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=1Finally, we do not recommend disabling HSTS, but if you need to, you can do so by setting ssl-hsts=0.