Securing Access with HTTPS

By the end of this lesson, you will be able to:

  • Explain why HTTPS is essential for a production Workbench deployment
  • Describe the roles TLS certificates and private keys play in securing access
  • Identify where certificates should live and how they should be permissioned
  • Recognize the configuration changes Workbench needs to serve traffic over HTTPS

1 Introduction

By default, Workbench serves traffic over unencrypted HTTP on port 8787. For any deployment beyond initial testing, you need to configure HTTPS so traffic between your users and the server, including credentials, code, and data science work, is encrypted and cannot be intercepted or tampered with. Many organizations have strict security policies requiring encrypted connections, and proper certificate management is fundamental to maintaining a secure data science platform.

Workbench has one extra consideration compared with a plain web server: it proxies user traffic to sessions, and the launcher communicates back to the server when sessions start. Both the browser-facing connection and the launcher callback address must use HTTPS, or session launches will fail with callback errors.

This lesson explains the concepts behind securing Workbench with TLS certificates. The accompanying lab walks you through placing the certificates correctly, setting their permissions, and editing the configuration.

NoteTimings for this chapter
  • Reading time: 10 minutes
  • Documentation reading time: 5 minutes
  • Hands-on exercise time: 15-30 minutes
TipRequired Reading

2 What TLS Provides

TLS (Transport Layer Security) secures the connection between a client and a server using two related files: a certificate and a private key.

The certificate is presented to clients and identifies your server. It is not secret: it is meant to be shared, which is why it can be readable by others. The private key, by contrast, is the secret that proves the server owns that certificate. If the private key is exposed, the security of the connection is compromised, so it must be readable only by the service account that runs Workbench. This asymmetry is the reason the certificate and private key have different permission settings.

Certificates must be in PEM format, and the file should contain the full certificate chain. Private keys cannot be protected with a passphrase. If yours has one, the documentation provides a command to remove it.

3 Certificate Placement and Permissions

Posit recommends storing the certificate and private key alongside the other Workbench configuration files, in /etc/rstudio/. Keeping them with the rest of the configuration makes the deployment easier to reason about and back up.

Both files must be owned by rstudio-server:rstudio-server so that Workbench can read them. Their modes differ to reflect their sensitivity: the certificate can be world-readable (mode 644), while the private key must be readable and writable only by its owner (mode 600). Getting these permissions wrong is a common cause of Workbench failing to start after a TLS change.

Before configuring Workbench, you can inspect your certificate with openssl x509 -text -noout -in <path_to_certificate_file.crt>. This checks that the file is in PEM format and lets you confirm the full certificate chain is present.

4 How Workbench Serves HTTPS

Enabling HTTPS requires a few settings in /etc/rstudio/rserver.conf and a restart of Workbench in the correct order:

  1. ssl-enabled=1 turns on SSL/TLS.
  2. ssl-certificate points to the full path of the certificate file.
  3. ssl-certificate-key points to the full path of the private key.
  4. launcher-sessions-callback-address must be updated to use https://, because the launcher needs to communicate back to the server using the correct protocol.

Once you have configured and restarted Workbench, users reach it over https://. You can confirm the change by checking that the browser shows a secure connection with no certificate warnings, and that sessions still start normally.

TipWhy is it relevant to me?

As you plan the TLS configuration for your own Workbench environment, keep these questions in mind:

  • Certificate source: Will you use certificates from your organization’s internal CA, a public CA such as Let’s Encrypt or DigiCert, or self-signed certificates?
  • Certificate chain and format: Does your certificate file include the complete chain, and is it in PEM format? Incomplete chains cause browser warnings.
  • Private key protection: Is the private key passphrase-free? Workbench cannot use passphrase-protected keys.
  • Renewal: What is your certificate’s expiration date? Plan renewal procedures to avoid service interruptions, and consider tools such as certbot for automated renewal.

In the accompanying lab, you will move the certificate and its key into place, set their ownership and permissions, and edit rserver.conf so Workbench serves traffic over HTTPS.