Secure cookies

By default, when Posit 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 Workbench to mark cookies as secure, you can add the following configuration option:



Secure authorization cookies values used by Posit Workbench have three components, separated by the pipe character. Here’s an example:

janedoe|Sat, 24 Sep 2022 17:46:21 GMT|GrA/vSHTFZiXglz4rRuBvH7anv/iaI+GzswvCokHJJA=

The values are as follows:

  1. The secure valuejanedoe in this case.
  2. The expiration date24 Sep 2022 17:46:21 GMT in this case. This prevents the cookie from being used after it has expired and helps guard against replay attacks.
  3. The signatureGrA/vSHTFZiXglz... in this case. The signature is an HMAC formed by combining the cookie’s secure value, the expiration date, and the secure cookie key secret (discussed below).

The cookie’s signature makes it impossible to tamper with its value or expiration date; for example, you could not modify this cookie to refer to a user other than janedoe without invalidating the signature.

Authorization cookies are further protected by the secure cookie attribute (described above), cannot be read by scripts as they are also marked HttpOnly, and are encrypted over the network when SSL is used.

Secret key

The secret key used to securely sign cookies is stored here by default:


As with other configuration files, however, you can cause it to be read from another location using the XDG_CONFIG_DIRS environment variable. The secure-cookie-key-file option in rserver.conf can also be used to set the location of the secure cookie key file.


When using Posit Workbench in low privilege mode (single-user, no root access), the secure cookie key is read from the server-user’s home directory instead, in ~/.cache/rstudio/secure-cookie-key; this location can be changed with the environment variable $XDG_CACHE_HOME.

The key file must be owned by the server user, and its permissions must be 600 (rw-------) to ensure that it cannot be read by other users. A user with access to the secure cookie key could theoretically forge login cookies, gaining access to other users’ sessions.

The key file’s contents must be a 32-digit hexadecimal value (only), as in the below example:

# /etc/rstudio/secure-cookie-key

Replacing or changing the key

The secret key is normally auto-generated from a secure random source the very first time the server starts up; it remains unchanged thereafter. It does not typically need to be manually changed.

However, if you need to generate a new value for any reason (for example if you have reason to believe the current value has been compromised), you can use the uuidgen utility to generate a new key value. For example, this command will generate a new UUID, remove the - characters, and update the value in the secure-cookie-key: uuidgen -x | tr -d '-' > /etc/rstudio/secure-cookie-key.

Replace the contents of the secure-cookie-key file with your new key value, then restart the server to apply the change.


Changing the secure cookie key’s value will invalidate all existing secure cookies, with the result that all users will need to sign in again.


In a load-balanced configuration, the secure cookie key’s contents must be the same among all nodes in the cluster, so that authentication cookie signatures can be validated regardless of which node processes an HTTP request on a user’s behalf. See the Load Balancing section for more information.

Same site cookies

Most browsers have adopted recently a new attribute for cookies called SameSite which enforces additional security requirements around the cookie. Workbench 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 ensure the delivery of Workbench cookies in this scenario, use the value www-same-site=none.


SameSite=None is insufficient without SSL enabled and may still prevent Workbench 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, Workbench 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 Workbench embedded into an iframe or frameset on compliant browsers by blocking all Workbench cookies.


Third-Party cookies (Safari 13+ compatibility)

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

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

Alternatively, you can place Workbench 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 Workbench. See Running with a Proxy for more information.


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

Back to top