OpenID Connect Authentication [PRO]

RStudio Workbench can be configured to authenticate users via OpenID Connect. This enables users to log in with their existing Single Sign-On (SSO) credentials and to be automatically authenticated to RStudio whenever they are already logged into their OpenID Provider (OP) account.

Enabling OpenID Connect

To enable authentication with OpenID you add the auth-openid option to the RStudio configuration file:

# /etc/rstudio/rserver.conf
auth-openid=1
Important

Once you enable authentication with OpenID, that becomes the exclusive means of authentication (you can’t concurrently use both PAM and OpenID authentication).

Important

OpenID authentication still requires PAM Sessions and sssd to automatically create local system accounts. Without them, local system accounts have to be provisioned manually one-by-one.

Configuring your OpenID Provider

In order to use OpenID with RStudio Workbench you need to register your server on your OP first.

Note

RStudio Workbench supports the OAuth2 “Authorization Code” flow with OpenID.

OpenID URLs

RStudio Workbench expects an OAuth2 callback in order to complete the OpenID authentication. The endpoint responsible for handling this callback from the OP is located at /openid/callback. For example, if your RStudio Workbench server is hosted at https://rstudio.example.com/ the callback URL will be https://rstudio.example.com/openid/callback. While registering RStudio Workbench on your OpenID Provider, this URL will be requested. Your server URL may also be requested as part of that setup.

Client Credentials

As part of the RStudio Workbench registration on your OP, a “client ID” and a “client secret” may be presented to you. You need to add a configuration file (/etc/rstudio/openid-client-secret) containing the client-id and client-secret. For example, the configuration file might look like this:

# /etc/rstudio/openid-client-secret
client-id=lllllllllllll-xxxxxxxxxxxxxxxxxxxxxx
client-secret=BhCC6rK7Sj2ZtPH0ord7lO1w

The /etc/rstudio/openid-client-secret file should have user read/write file permissions (i.e., 0600) to protect its contents from other users. You can ensure this as follows:

$ sudo chmod 0600 /etc/rstudio/openid-client-secret
Important

The above client-id and client-secret aren’t the actual values you’ll use. Rather, you should substitute the values that you obtained from your OP when registering your site for OAuth 2.0 authentication.

Client Secret Encryption

An unencrypted value in the client-secret option of the /etc/rstudio/openid-client-secret file must only be used temporarily for testing purposes. A warning will be present in RStudio log output when an unencrypted secret is being used.

We strongly recommend encrypting the client secret using the command rstudio-server encrypt-password. This way, if you have to backup your configuration, save it to a repository or share it with RStudio Support, your OpenID client secret will be protected.

Use the following steps to encrypt the OpenID client secret:

  • Run the command sudo rstudio-server encrypt-password and enter the client secret.
  • Copy the resulting encrypted secret printed in the terminal.
  • Add or replace the client-secret option in the openid-client-secret file using the encrypted secret copied above.
  • Restart RStudio. Confirm it operates normally. You should no longer see a warning about unencrypted secret in RStudio logs.
Note

Alternatively, you can also “pipe” your secret to the rstudio-server encrypt-password command to skip the prompt. Useful when the secret is already stored elsewhere. For example:

cat secretfile | sudo rstudio-server encrypt-password

OpenID Issuer and Well-Known configuration

RStudio Workbench also needs to be configured to be able to authenticate the authorization codes returned by the OP. In order to do that, RStudio needs to know the location of the OP with its “issuer” URL. This can be done by adding the option auth-openid-issuer. This must be an HTTPS URL and the location of the /.well-known/openid-configuration metadata discovery. For example, if your OpenID issuer is https://op.example.com/ the discovery endpoint should be https://op.example.com/.well-known/openid-configuration.

# /etc/rstudio/rserver.conf
auth-openid-issuer=https://op.example.com

OpenID Claims

Your OP must return at least one claim matching a valid Linux account username. See PAM Basics for details on username handling. By default, RStudio Workbench will look for a claim called preferred_username (case-sensitive). If you wish to use a different claim, add the option auth-openid-username-claim with the appropriate value.

# /etc/rstudio/rserver.conf
auth-openid-username-claim=other

Advanced Options

Depending on your choice for the username claim your OpenID Provider may require the initial request to contain a certain “scope”. RStudio Workbench automatically includes the scopes openid, email and profiles as part of the authentication. If you wish to include additional scopes, use the option auth-openid-scopes with a space-separated list of values.

# /etc/rstudio/rserver.conf
auth-openid-scopes=scope1 scope2
Important

Quotation marks are not accepted around the scope values.

Proxy Considerations

If you are running RStudio behind a proxy, you will need to configure your proxy in a way that RStudio can tell the OP to redirect back to the correct location. There are number of options to choose from as described in Running with a Proxy.

The use of the X-RStudio-Request header in your proxy is recommended and the only method which works behind a path-rewriting proxy. In this case, the proxy must set the X-RStudio-Request header to the exact complete URL as requested by the browser. For example if your proxy was set up to serve RStudio requests at https://testdomain.com/rstudio/ and an incoming request for /home came in, your proxy should set X-RStudio-Request: https://testdomain.com/rstudio/home which would allow RStudio to know about the added path prefix /rstudio.

If your proxy does not add path prefixes, RStudio is also compatible with two options using commonly available HTTP proxy headers:

  • The headers X-Forwarded-Host, X-Forwarded-Proto, and X-Forwarded-Port.
  • Or the header Forwarded with host, and proto values.

When using path-rewriting proxies, it’s also recommended to use either the header X-RStudio-Root-Path or the option www-root-path to indicate the path defined for RStudio by the proxy. For example, if your URL to RStudio is www.example.com/rstudio your proxy should send the header X-RStudio-Root-Path: /rstudio or you should use:

# /etc/rstudio/rserver.conf
www-root-path=/rstudio

If none of the headers above are set by the proxy, RStudio will attempt to redirect back to the address present in the Host header and it will determine the protocol (http or https) based on its current configuration.

If you are running behind a proxy but cannot set headers for whatever reason, and www-root-path is not the right choice, you can use the auth-openid-base-uri option in the RStudio configuration file to accomplish the same purpose:

# /etc/rstudio/rserver.conf
auth-openid-base-uri=http://testdomain.com/rstudio/

Outgoing Proxies

Some OpenID authentication features require RStudio to make a call to an external service over HTTP or HTTPS; for example, to retrieve the provider’s OpenID configuration from a known endpoint. If your environment requires an HTTP or HTTPS proxy for outbound requests, you must set the appropriate proxy environment variables for RStudio’s server process so that it uses the proxy when making the request.

One way to do this is to add the variables to env-vars; for example:

# /etc/rstudio/env-vars
HTTP_PROXY=http://192.168.1.1:8080
HTTPS_PROXY=http://192.168.1.1:8080
NO_PROXY=localhost,192.168.1.10

Load Balancing Considerations

Because RStudio stores OpenID authentication context in server memory during the OAuth flow, the entire authentication flow must be completed on a single server. If you’re using an external load balancer in front of RStudio, you will experience authentication errors if the HTTP requests associated with the authentication flow are not all routed to the same server.

For this reason, you must enable sticky sessions in your external load balancer when using OpenID authentication. This feature is sometimes called “sticky cookies” or “session affinity”. Consult the documentation for your load balancing software for details; for example if you’re using the Amazon Web Services Application Load Balancer (AWS ALB), more information can be found in Sticky Sessions for your Application Load Balancer.

Troubleshooting

Additional information about the OpenID flow and the received claims may be written to the logs. Be sure to configure rserver logs to output debug level messages in /etc/rstudio/logging.conf to see these entries.