OpenID Connect Authentication

Workbench

Posit 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 Workbench 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 Workbench 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 Workbench you need to register your server on your OP first.

Note

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

OpenID URLs

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 Workbench server is hosted at https://rstudio.example.com/ the callback URL will be https://rstudio.example.com/openid/callback. While registering 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 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 Workbench 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 Workbench 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 Workbench. Confirm it operates normally. You should no longer see a warning about unencrypted secret in Workbench 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

Workbench also needs to be configured to be able to authenticate the authorization codes returned by the OP. In order to do that, Workbench 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, 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

OpenID claim data are returned by the OpenID Provider (OP), so configuring custom claims and scopes to suit your use-cases must be completed externally to Workbench. Not all OPs provide this functionality.

Note that, because the username claim must match a Linux account username, the username claim is subject to the same restrictions as those applied by the operating system to account usernames. See the CAVEATS section on the useradd man-page for more information about username restrictions. To summarize: portable usernames are limited to 32 characters in length, and must only contain alphanumeric characters, underscores, and dashes. Optionally, they can end with a ‘$’ dollar sign character.

These restrictions my vary depending on the flavor of Linux, but the 32 character limit is common to most. Taking advantage of operating-system-specific naming conventions may reduce the portability of usernames.

Also, be aware that Workbench currently does not support custom post-processing (or mapping) of claims.

Advanced options

Depending on your choice for the username claim your OpenID Provider may require the initial request to contain a certain “scope”. 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 Workbench behind a proxy, you will need to configure your proxy in a way that Workbench 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 Workbench 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 Workbench to know about the added path prefix /rstudio.

If your proxy does not add path prefixes, Workbench 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 Workbench by the proxy. For example, if your URL to Workbench 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, Workbench 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 Workbench 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 Workbench 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 Workbench’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

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.