4 Access and Security

4.1 Network Port and Address

After initial installation RStudio accepts connections on port 8787. If you wish to listen on a different another port you can modify the www-port option. For example:

/etc/rstudio/rserver.conf

www-port=80

By default RStudio binds to address 0.0.0.0 (accepting connections from any remote IP). You can modify this behavior using the www-address option. For example:

/etc/rstudio/rserver.conf

www-address=127.0.0.1

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

4.2 IP Access Rules

RStudio Workbench can be configured to deny access to specific IP addresses or ranges of addresses. Access rules are defined in the configuration file /etc/rstudio/ip-rules

Access rules are established using the allow and deny directives and are processed in order, with the first matching rule governing whether a given address is allowed or denied. For example, to allow only clients within the 192.168.1.0/24 subnet but also deny access to 192.168.1.10 you would use these rules:

/etc/rstudio/ip-rules

deny    192.168.1.10
allow   192.168.1.0/24
deny    all

All clients outside of the specified subset are denied access because of the deny all rule at the end of the configuration.

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

4.3 Frame Origin

For security reasons, RStudio will not load inside a browser frame (such as a frameset or IFrame) by default. You can modify this behavior by using the www-frame-origin option. For example, if you would like to host RStudio inside a browser frame at example.com, you can tell RStudio to allow this as follows:

/etc/rstudio/rserver.conf

www-frame-origin=example.com

There are several special values available for the www-frame-origin option:

Value Meaning
none The default; do not allow RStudio to load in any frame.
same Allow RStudio to load in a frame if it has the same origin (host and port) as RStudio.
any Allow RStudio to load in a frame from any origin (not recommended)
my-domain.com Allow RStudio to load in a frame at my-domain.com

To interact programmatically with RStudio in an IFrame, see the Tutorial API.

4.4 Same Site cookies

Most browsers have adopted recently a new attribute for cookies called SameSite which enforces additional security requirements around the cookie. RStudio does not define this attribute by default but you can use the option www-same-site for that purpose.

For example, the value SameSite=None is required by certain browsers (i.e. Chrome 84+) for embedding sites into an IFrame or frameset. To ensuring the delivery of RStudio cookies in this scenario, use the value www-same-site=none.

/etc/rstudio/rserver.conf

www-same-site=none

Important: SameSite=None is insufficient without SSL enabled and may still prevent RStudio from working over non-SSL connections.

Some browsers will not behave as expected in the presence of the SameSite=None; Safari 12 on MacOS 10.14 and iOS 12.x or older notably will not work. To workaround these limitations, RStudio will emit a pair of cookies, one with SameSite=None for standard-conforming browsers and a “legacy” cookie without SameSite for non-conforming browsers.

You also can use the value www-same-site=lax to mark cookies as SameSite=Lax what effectively prohibits the use of RStudio embedded into an IFrame or frameset on compliant browsers by blocking all RStudio cookies.

/etc/rstudio/rserver.conf

www-same-site=lax

4.5 Compatibility with Safari 13+

Starting in Safari 13, if you are loading RStudio inside a browser frame on a completely different domain all cookies will be blocked because those will be considered third-party cookies.

Embedding RStudio in a subdomain of the main site causes its cookies to be considered first-party, allowing RStudio to work.

Alternatively, you can place RStudio in the same domain as the main wrapping site but under a different URL path. This requires using a proxy in front of both the main site and RStudio. See Running with a Proxy below for more information.

Note: In a near future, most browsers vendors plan to apply the same restrictions to cookies in some degree.

4.6 Additional Security Considerations

To help mitigate against CSRF attacks, RStudio can automatically reject any request originating from an Origin or Referer that does not match the Host, X-Forwarded-Host, Forwarded: host or X-RStudio-Request headers. To enable this check, add the following configuration:

/etc/rstudio/rserver.conf

www-enable-origin-check=1

In some cases, such as if running behind a proxy that you cannot modify, this check may be too strict, and can prevent access to RStudio, causing requests to return a 400 status. In such cases, it is recommended that you disable the check. Origin checking is currently disabled by default, but will likely be enabled by default in a future version of RStudio.

You may wish to consider some origins to be safe in all cases, causing RStudio to consider such Origin or Referer values to be allowed instead of being rejected, even if they do not match a Host header. To specify such origins, add each of them as a www-allow-origin setting in rserver.conf. For example:

/etc/rstudio/rserver.conf

www-allow-origin=mysubdomain.mydomain.com
www-allow-origin=*.mydomain2.com

Note that wildcards (*) are accepted and will match any character, including hostname separators. For instance, the previous example of *.mydomain2.com will match both foo.bar.mydomain2.com and foo.mydomain2.com.

4.7 Additional Headers

In some cases, you may need to have RStudio set additional headers on client responses. To do this, simply specify server-add-header for each header that you need to add, in the form Header Name:Header Value. For example, to have the server set a few extra custom headers:

/etc/rstudio/rserver.conf

server-add-header=X-Header-1:Value 1
server-add-header=X-Header-2:Value 2

4.8 Secure Sockets (SSL)

4.8.1 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

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

4.9 SSL Ports

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

  1. SSL is bound to port 443 (enabling access using the standard https protocol within the browser)
  2. 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.

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

4.10 Cookies

By default, when RStudio Workbench is configured with SSL, all authorization cookies are marked with the secure cookie attribute. If you wish to use your own SSL termination but force RStudio to mark cookies as secure, you can add the following configuration option:

/etc/rstudio/rserver.conf

auth-cookies-force-secure=1

4.11 Server Permissions

4.11.1 Server Account

RStudio runs as the system root user during startup and then drops this privilege and runs as a more restricted user. RStudio then re-assumes root privilege for a brief instant when creating R sessions on behalf of users (the server needs to call setresuid when creating the R session, and this call requires root privilege).

The user account that RStudio runs under in the normal course of operations is rstudio-server. This account is automatically added to the system during installation and is created as a system rather than end user account (i.e. the --system flag is passed to useradd).

4.11.1.1 Alternate Server Account

You can configure RStudio so that it will run from an alternate account with the following steps:

  1. Create a new system user (if the one you want to use doesn’t already exist)
  2. Assign this user to the server-user option in the /etc/rstudio/rserver.conf configuration file (see example below)
  3. Restart RStudio

For example, to shutdown the server and create a new system user named rs-user you’d use the following commands:

sudo rstudio-server stop
sudo useradd --system rs-user

Then edit the /etc/rstudio/rserver.conf configuration file as follows:

/etc/rstudio/rserver.conf

server-user=rs-user

Finally, restart RStudio to begin running under the new user:

sudo rstudio-server start

4.11.2 umask

By default, RStudio sets its umask to 022 on startup. If you don’t want this behavior, for instance because you’d prefer the server process to use the default umask set in init, it can be disabled as follows:

/etc/rstudio/rserver.conf

server-set-umask=0

4.12 Running with a Proxy

4.12.1 Overview

If you are running RStudio behind a proxy server you need be sure to configure the proxy server so that it correctly handles all traffic to and from RStudio.

Beyond the normal reverse proxy configuration you’d apply for any HTTP server application, you also need to ensure that websockets are forwarded correctly between the proxy server and RStudio to ensure that all RStudio functions work correctly. In particular, they’re needed to ensure that Shiny applications run from within the IDE work properly - if not, you may find that Shiny applications “gray out” and close without you being able to interact with them.

It’s also important to ensure that your reverse proxy uses a relatively lenient connection timeout; we recommend 60 seconds. Several components of RStudio use HTTP Long Polling to push information to the browser; a connection timeout of 30 seconds or fewer will result in HTTP 504 (gateway timeout) errors from the reverse proxy.

This section describes how to correctly configure a reverse proxy with Nginx and Apache.

4.12.2 Nginx Configuration

On Debian or Ubuntu a version of Nginx that supports reverse-proxying can be installed using the following command:

sudo apt-get install nginx

On CentOS or Red Hat you can install Nginx using the following command:

sudo yum install nginx

To enable an instance of Nginx running on the same server to act as a front-end proxy to RStudio you would add commands like the following to your nginx.conf file. Note that you must add code to proxy websockets in order to correctly display Shiny apps and R Markdown Shiny documents in RStudio. Also note that if you are proxying to a server on a different machine you need to replace references to localhost with the correct address of the server where you are hosting RStudio.

http {

  map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
  }
  
  server {
    listen 80;
    
    
    location / {
      proxy_pass http://localhost:8787;
      proxy_redirect http://localhost:8787/ $scheme://$host/;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_read_timeout 20d;
      # Use preferably
      proxy_set_header X-RStudio-Request $scheme://$host:$server_port$request_uri;
      # OR existing X-Forwarded headers
      proxy_set_header X-Forwarded-Host $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      # OR alternatively the Forwarded header (just an example)
      proxy_set_header Forwarded "host=$host:$server_port;proto=$scheme;";
    }
  }
}

If you want to serve RStudio from a custom path (e.g. /rstudio) you would edit your nginx.conf file as shown below:

http {

  map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
  }
  
  server {
    listen 80;
    
    location /rstudio/ {
      rewrite ^/rstudio/(.*)$ /$1 break;
      proxy_pass http://localhost:8787;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_read_timeout 20d;
      # Use preferably
      proxy_set_header X-RStudio-Request $scheme://$host:$server_port$request_uri;
      proxy_set_header X-RStudio-Root-Path /rstudio
      # OR let the proxy rewrite the root path
      proxy_redirect http://localhost:8787/ $scheme://$host/rstudio/;
      proxy_cookie_path / /rstudio;
      # OR existing X-Forwarded headers
      proxy_set_header X-Forwarded-Host $host;
      proxy_set_header X-Forwarded-Proto $scheme;
      # OR alternatively the Forwarded header (just an example)
      proxy_set_header Forwarded "host=$host:$server_port;proto=$scheme;";
    }

Note: The header X-RStudio-Root-Path and the configuration option www-root-path server the same purpose. If either is set RStudio will always return cookies and redirects for the correct path, without requiring rewrite assistance from the proxy. The header value has precedence over the configuration value.

/etc/rstudio/rserver.conf

www-root-path=/rstudio

After adding these entries you’ll then need to restart Nginx so that the proxy settings take effect:

sudo /etc/init.d/nginx restart

Note that RStudio needs the X-RStudio-Request, X-Forwarded-[Host|Port|Proto], or Forwarded headers set for various security reasons, and nginx does not supply this header by default. It must contain the original Host value of the request, which is usually set to $host in the nginx configuration file.

In some cases, such as when streaming job statuses from the launcher, the default response buffering in nginx can be too slow for delivering real-time updates, especially when configured to use SSL. If job output streams are not working properly from the home page, we recommend disabling response buffering by adding the following line under the server directive:

server {
  # ... follows previous configuration
  proxy_buffering off;
}

4.12.3 Apache Configuration

To enable an instance of Apache running on the same server to act as a front-end proxy to RStudio you need to use the mod_proxy and mod_proxy_wstunnel modules. The steps for enabling this module vary across operating systems so you should consult your distribution’s Apache documentation for details. Apache as reverse proxy already includes X-Forwarded-Host (with port) and X-Forwarded-Proto by default.

On Debian and Ubuntu systems Apache can be installed with mod_proxy using the following commands:

sudo apt-get install apache2
sudo apt-get install libapache2-mod-proxy-html
sudo apt-get install libxml2-dev

Then, to update the Apache configuration files to activate mod_proxy you execute the following commands:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel

On CentOS and RedHat systems Apache can be installed with mod_proxy and mod_proxy_wstunnel by following the instructions here:

http://httpd.apache.org/docs/2.4/platform/rpm.html

By default with Apache 2.4, mod_proxy and mod_proxy_wstunnel should be enabled. You can check this by opening the file /etc/httpd/conf.modules.d/00-proxy.conf and making sure the following lines are included and not commented out:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so

Once you have enabled mod_proxy and mod_proxy_wstunnel in your Apache installation you need to add the required proxy commands to your VirtualHost definition. Note that you will also need to include code to correctly proxy websockets in order to correctly proxy Shiny apps and R Markdown documents within RStudio. Also note that if you are proxying to a server on a different machine you need to replace references to localhost with the correct address of the server where you are hosting RStudio.

<VirtualHost *:80>

  <Proxy *>
    Allow from localhost
  </Proxy>

  RewriteEngine on
  RewriteCond %{HTTP:Upgrade} =websocket
  RewriteRule /(.*)     ws://localhost:8787/$1  [P,L]
  RewriteCond %{HTTP:Upgrade} !=websocket
  RewriteRule /(.*)     http://localhost:8787/$1 [P,L]
  ProxyPass / http://localhost:8787/
  ProxyPassReverse / http://localhost:8787/
  # Use preferably this (store variable values with dummy rewrite rules)
  RewriteRule . - [E=req_scheme:%{REQUEST_SCHEME}]
  RewriteRule . - [E=http_host:%{HTTP_HOST}]
  RewriteRule . - [E=req_uri:%{REQUEST_URI}]
  RequestHeader set X-RStudio-Request "%{req_scheme}e://%{http_host}e%{req_uri}e"
  ProxyRequests Off

</VirtualHost>

Note that if you want to serve RStudio from a custom path (e.g. /rstudio) you would replace the directives described above to:

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket
RewriteRule /rstudio/(.*)     ws://localhost:8787/$1  [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket
RewriteRule /rstudio/(.*)     http://localhost:8787/$1 [P,L]
ProxyPass /rstudio/ http://localhost:8787/
# Use preferably this (store variable values with dummy rewrite rules)
RewriteRule . - [E=req_scheme:%{REQUEST_SCHEME}]
RewriteRule . - [E=http_host:%{HTTP_HOST}]
RewriteRule . - [E=req_uri:%{REQUEST_URI}]
RequestHeader set X-RStudio-Request "%{req_scheme}e://%{http_host}e%{req_uri}e"
RequestHeader set X-RStudio-Root-Path "/rstudio"
# Or alternatively
ProxyPassReverse /rstudio/ http://localhost:8787/
ProxyPassReverseCookiePath  "/"  "/rstudio"
ProxyRequests Off

Note: The header X-RStudio-Root-Path and the configuration option www-root-path server the same purpose. If either is set RStudio will always return cookies and redirects for the correct path, without requiring rewrite assistance from the proxy. The header value has precedence over the configuration value.

/etc/rstudio/rserver.conf

www-root-path=/rstudio

Finally, after you’ve completed all of the above steps you’ll then need to restart Apache so that the proxy settings take effect:

sudo /etc/init.d/apache2 restart

4.12.4 RStudio Configuration

If your RStudio Workbench and proxy server are running on the same machine you can also change the port RStudio Workbench listens on from 0.0.0.0 (all remote clients) to 127.0.0.1 (only the localhost). This ensures that the only way to connect to RStudio is through the proxy server. You can do this by adding the www-address entry to the /etc/rstudio/rserver.conf file as follows:

www-address=127.0.0.1

Note that you may need to create this config file if it doesn’t already exist.

4.12.5 Custom Paths and Path-Rewriting Proxies

In the examples above we have configurations where RStudio is served by the proxy under a custom /rstudio path. This is called a path-rewriting proxy setup.

RStudio can use different combinations of HTTP headers and/or options to determine its location when path-rewriting in is use:

  • Use X-RStudio-Request if possible. This way RStudio knows exacly the address presented in the user’s browser.
    • Otherwise, you must use X-Forwarded-* family of headers or the Forwarded header.
  • Use X-RStudio-Root-Path if possible. This way RStudio knows which portion of the path was added by the proxy.
    • Alternatively, use the option www-root-path for the same effect.
    • Otherwise, you must use additional options in your proxy configuration to adjust redirects and cookies for the right path.

The most reliable configuration is using X-RStudio-Request and X-RStudio-Root-Path defined as in the examples above. There’s little involvement of the proxy when using these headers.

If you have little experience with proxies but still want to use a custom path, we recommend using the www-root-path option in RStudio and at least the headers X-Forwarded-Host and X-Forwarded-Proto.

Finally, if you want the proxy to have total control of custom path then define the rewrite rules yourself directly in the proxy configuration based on the alternatives suggested in the example above. In this case, do not use the option www-root-path or the header X-RStudio-Root-Path.

4.12.6 Customizing Default Proxy

RStudio Workbench exposes itself over TCP by means of an nginx proxy instance that runs as the rserver-http process on the local machine. In some cases, this proxy instance may need to be customized.

In order to customize it, you can create any of the following three files. Each file modifies the nginx configuration at /var/lib/rstudio-server/conf/rserver-http.conf in the following way:

  • /etc/rstudio/nginx.http.conf - allows you to add additional nginx directives under the root http node, and should be used for altering basic HTTP settings
  • /etc/rstudio/nginx.server.conf - allows you to add additional nginx directives under the server node, and should be used for altering basic server settings
  • /etc/rstudio/nginx.site.conf - allows you to add additional nginx directives under the location / node, and should be used for altering responses sent from RStudio

Simply add the desired nginx configuration in the files above to modify the desired section - the contents of each file is copied into the rserver-http.conf template verbatim. Then, restart rstudio-server for the changes to take effect.

In most cases, you should not need to create these files and modify the nginx template that is provided.