Lab 2 – Setting up HTTPS

1 Learning Objectives

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

  1. Install and configure TLS certificates for secure HTTPS access to Posit Workbench
  2. Update Workbench configuration files to enable SSL and configure the launcher callback URL

2 Introduction

In this lab, you will configure Workbench to use HTTPS with TLS certificates. This ensures encrypted communication between users’ browsers and the Workbench server, protecting sensitive data (including credentials, code, and data science work) from interception or tampering.

Understanding TLS configuration is essential for any production Workbench deployment. Many organizations have strict security policies requiring encrypted connections, and proper certificate management is fundamental to maintaining a secure data science platform.

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

3 Move the Certificate to the Correct Location

For this lab, the certificate and private key are located in the ~/certs/ folder in the ubuntu user’s home directory. For Workbench, we recommend storing these files in the same folder as the other configuration files, in /etc/rstudio/.

Move the files from the certs folder in your home directory to /etc/rstudio/.

4 Set File Permissions and Ownership

Once the files are in the /etc/rstudio folder, set the correct permissions and ownership for both files. Ensure that the files have both the appropriate owner and mode using the chown and chmod commands.

Both files must be owned by rstudio-server:rstudio-server.

The certificate must be readable and writable by the owner, and readable by others (644). The private key must be readable and writable only by the owner (600).

TipInspecting the Certificate

To check the content of your certificate file, and to ensure that the full certificate chain is present in your file, you can run:

Terminal
openssl x509 -text -noout -in <path_to_certificate_file.crt>

This command also checks that the certificate is in PEM format, which Workbench requires. The documentation provides commands to convert certificates in other formats to PEM.

As indicated in our documentation, the private key cannot be protected with a passphrase. If there is one, you can remove it with this command:

Terminal
openssl rsa -in [original.key] -out [new.key]

5 Edit the Configuration File

Edit the /etc/rstudio/rserver.conf file to configure Workbench to use these certificates, by adding the following:

/etc/rstudio/rserver.conf
ssl-enabled=1
ssl-certificate=/etc/rstudio/certificate.crt
ssl-certificate-key=/etc/rstudio/private.key

Now that your server is going to use HTTPS, update launcher-sessions-callback-address to the URL of your installation.

In this Instruqt training environment, you can get your server URL by running:

Terminal
echo https://$HOSTNAME.$_SANDBOX_ID.instruqt.io

You can also find this URL in the instruction window (bottom right corner).

In a production deployment, your URL will be the actual hostname or fully qualified domain name (FQDN) assigned to your Workbench server (e.g., https://workbench.example.com).

Add or update the launcher-sessions-callback-address in /etc/rstudio/rserver.conf:

/etc/rstudio/rserver.conf
launcher-sessions-callback-address=https://YOUR-HOSTNAME-HERE

Restart Workbench using the proper restart sequence:

Terminal
sudo /usr/sbin/rstudio-server stop && \
sudo /usr/bin/rstudio-launcher stop && \
sudo /usr/bin/rstudio-launcher start && \
sudo /usr/sbin/rstudio-server start

Log in using the posit_admin user (password: posit_admin) and verify that:

  • The browser shows a secure HTTPS connection (look for the padlock icon in the address bar)
  • You can create and access sessions normally
  • There are no certificate warnings or errors

6 Check Your Understanding

Before proceeding to the next lab, make sure you can answer these questions:

  1. TLS Certificates: What are the correct file permissions for the certificate file and the private key file? Why are these permissions important for security?

  2. Configuration: What three configuration parameters must be set in /etc/rstudio/rserver.conf to enable HTTPS? Why must you also update the launcher-sessions-callback-address parameter?

6.1 Question 1

The certificate file must have permissions 644 (readable and writable by owner, readable by others), and the private key must have permissions 600 (readable and writable only by owner). Both files must be owned by rstudio-server:rstudio-server.

These permissions are important because:

  • The certificate is public information and can be world-readable
  • The private key must be protected from unauthorized access. Only the rstudio-server process needs to read it. Allowing others to read it is a security risk.

6.2 Question 2

Three required configuration parameters:

  1. ssl-enabled=1 - Enables SSL/TLS
  2. ssl-certificate=/etc/rstudio/certificate.crt - Path to certificate file
  3. ssl-certificate-key=/etc/rstudio/private.key - Path to private key file

You must also update launcher-sessions-callback-address to use https:// instead of http:// because the launcher needs to communicate back to the server using the correct protocol. If you do not update this value, session launches will fail with callback errors.

7 Looking Back, Planning Ahead

When planning TLS configuration for your production Workbench environment, ensure you have answers to these questions:

  • Certificate Source: Will you use certificates from your organization’s internal CA, a public CA (Let’s Encrypt, DigiCert, etc.), or self-signed certificates?
  • Certificate Chain: Does your certificate file include the complete certificate chain? Incomplete chains cause browser warnings.
  • Certificate Format: Is your certificate in PEM format? If not, you will need to convert it using OpenSSL.
  • Private Key Protection: Is the private key passphrase-free? Workbench cannot use passphrase-protected keys.
  • Certificate Renewal: What is your certificate’s expiration date? Plan for renewal procedures to avoid service interruptions.
  • Automation: Consider using tools like certbot for automated certificate renewal with Let’s Encrypt.