Secure Sockets (SSL)

Workbench

Overview

If your Posit Workbench installation is running on a public network, it is best practice to secure your network. To increase security, configure Workbench to encrypt traffic using Transport Layer Security (TLS), also known as Secure Sockets Layer (SSL). SSL doesn’t come preconfigured since it requires certificates signed by a Certificate Authority (CA) that is trusted by all parties.

Generally, enable SSL by adding the following to the /etc/rstudio/rserver.conf file:

/etc/rstudio/rserver.conf
ssl-enabled=1

Read through the following sections before attempting to configure SSL.

Secure session communication

Local sessions

For local sessions, data is transmitted to sessions securely from Workbench to the session using Unix domain sockets.

Job Launcher sessions

Since Job Launcher sessions can live on a separate host, Workbench uses SSL connections by default to encrypt traffic over the network.

Workbench auto-provisions the required SSL certificates, creating one for each user. These certificates are accessible only to Workbench and the session user. The certificates are temporarily stored 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.

Important

By default, the system enables session SSL, but for data security, explicitly configure SSL for Workbench and the Job Launcher when enabling it.

Certificate management

Although auto-generated certificates are easy to use, they may not adhere to security policies that require use of certificates explicitly created using a different process.

In that case, configure Workbench to use externally created session SSL certificates.

Manually create SSL certificates

To manually create your own SSL certificates and configure Workbench to use them, the SSL session needs to point to the location of the public certificate and private key (both stored in the PEM format). These files must be accessible to the session user. Additionally, the paths can make use of the environment variables ${USER} and ${HOME}. For example:

# /etc/rstudio/rserver.conf
session-ssl-cert=/home/${USER}/cert.pem
session-ssl-cert-key=/home/${USER}/key.pem

Workbench verifies the session host against the certificate’s common name (CN) and subject alternative name (SAN) fields. When using load balancing, Slurm, or Kubernetes, the certificate must be valid for all session hosts. Therefore, wildcard IP addresses and domain names are supported.

Important

When creating your own certificates for session SSL, the private key for the certificates is available to the session user. They are not maintained with the level of secrecy required for a public website that is accessed via public domain. Do not 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.

Disable certificate verification

Important

It is strongly recommended to leave certificate verification enabled when using Workbench in production.

Debugging or development may require you to disable certificate verification for session SSL connections.

  • To disable certificate verification for session SSL connections, disable session-ssl-verify-certs:

    # /etc/rstudio/rserver.conf
session-ssl-verify-certs=0

Manually provision certificates

  • If you are externally provisioning certificates using an authority that is not trusted by your server’s CA trust list, add the signing certificate to Workbench using:

    # /etc/rstudio/rserver.conf
session-ssl-cert-authority=/etc/ssl/certs/sessionRootCert.pem

    This path is not accessed by the session, only by the Workbench server. It cannot use environment variables from the session user’s environment.

SSL for private secure networks

You can 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=0
    Caution

    It 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.

Supported SSL protocols

By default, Workbench supports the following protocols for SSL:

  • TLSv1
  • TLSv1.1
  • TLSv1.2
  • TLSv1.3

Configure the list of supported protocols via the ssl-protocols option.

  • The following example sets TLSv1.1 and TLSv1.2 as the only protocols:

    # /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.

Not all protocols may be available on your system:

  • TLS 1.1 and 1.2, require OpenSSL 1.0.1 (or higher)
  • TLS 1.3 requires OpenSSL 1.1.1 (or higher) built with TLS 1.3 support

SSL ports

When 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

Changes to the configuration do not take effect until the server is restarted.

HTTP Strict Transport Security

When SSL is enabled, 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.

If HTTPS issues arise it can be difficult to address them when the browser is locked to HTTPS because of HSTS. Therefore, by default, Workbench sets this period of time to one day (84600 seconds). 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 Workbench is hosted support HSTS, you can extend HSTS protection to them as well using the ssl-hsts-include-subdomains option:

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

This doesn’t happen by default since Workbench does not know what other services it’s sharing a domain with. However, it’s a recommended security best practice, so you should enable it, if possible.

Although we do not recommend disabling HSTS, you can disable it by setting ssl-hsts=0.

Set up SSL

Requirements

  • An SSL certificate
  • The location of your SSL certificate and key

Configure SSL

  • To configure SSL, update the /etc/rstudio/rserver.conf file. For example:

    /etc/rstudio/rserver.conf
    1ssl-enabled=1
2ssl-certificate=/var/certs/your_domain_name.crt
3ssl-certificate-key=/var/certs/your_domain_name.key
    1
    Enable SSL
    2
    Add the SSL certificate location
    3
    Add the SSL certificate key

Encode the .crt file in PEM format:

  • The first line of the file should read as:

    -----BEGIN CERTIFICATE-----

  • And, the contents of the file should be base64-encoded data.

    For alternate formats, such as DER or PKCS#12, use the openssl CLI tool to convert it to PEM:

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

When installing the certificate .crt file, link 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 to link 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.

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
    Note

    When using an existing load balancing environment and enabling or disabling SSL, the load balancing cluster needs to be reset. See Load Balancing Configuration for more information.

Use SSL for web users

If your configuration of Workbench is accessed directly by end users, see the SSL configuration section (above), which describes how you can ensure that HTTPS is used when Workbench is accessed via a web browser. This doesn’t apply if you are terminating SSL upstream, for example, when you are using nginx or Apache in front of Workbench (as described in Running with a Proxy) and handling SSL there.

Use SSL for the Job Launcher

Ensure that communication with the Job Launcher is encrypted by setting launcher-use-ssl=1 as follows:

/etc/rstudio/rserver.conf
launcher-use-ssl=1

Additional configuration for the Job Launcher is required to make it possible to connect to it over SSL. See Job Launcher Configuration for details.

Example Launcher configuration:

/etc/rstudio/launcher.conf
enable-ssl=1
certificate-file=/var/certs/your_domain_name.crt
certificate-key-file=/var/certs/your_domain_name.key

Restrict TLS versions

Before continuing, review the supported TLS versions (above).

Workbench supports many different SSL protocols for compatibility with older browsers, but several are no longer considered secure. We recommend disabling support for all SSL protocols except the most recent two, TLS 1.2 and 1.3. See the SSL protocols section (above) for more information.

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

Use HTTP Strict Transport Security (HSTS)

When configured with SSL, Workbench uses HTTP Strict Transport Security automatically. This is a security setting that forces the browser to always use HTTPS when connecting to Workbench. We recommend including the maximum age to 1 year, and extending coverage to subdomains.

/etc/rstudio/rserver.conf
ssl-hsts-max-age=31536000
ssl-hsts-include-subdomains=1

This ensures that the browser can’t connect via HTTP to the domain running Workbench (and any of its subdomains) for one year.

Using SSL with RStudio Server Open Source

Workbench has built-in SSL and HTTPS controls, as described in this section. However, much of the same advice applies if you are securing an installation of the Open Source edition of RStudio Server. You can run RStudio Server behind a reverse proxy, such as Nginx, and perform SSL termination upstream.

Additional resources

For a complete list of rserver.conf configuration options, please see the Workbench Administration Guide Appendix.

Back to top