Custom OAuth Credentials

Workbench | Preview Enhanced Advanced

Workbench can provide user-specific OAuth credentials for sessions that integrate with any OAuth 2.0-compliant service that supports the authorization code flow. These integrations allow users to securely access third-party APIs and services programmatically from Workbench sessions without managing credentials manually.

This feature is currently in Preview. It is designed to support standard OAuth 2.0 services; however, specific compatibility may vary across different providers.

Requirements

Important

Currently, this feature is only supported for Positron Pro, RStudio Pro, and VS Code sessions.

Before you begin, you must:

  • Ensure that end users are using HTTPS to access Workbench. For security reasons, web browsers do not allow OAuth flows to take place without HTTPS. For additional information, see the Mozilla Developer - Secure contexts documentation.
  • Ensure you have an OAuth 2.0-compliant service that supports the authorization code flow
  • Enable the Job Launcher with the launcher-sessions-callback-address setting configured correctly. See the Job Launcher section for more information.
  • Have administrator access to configure OAuth applications with your chosen service providers.
  • Ensure that the Workbench service is configured to use the proxy if your environment requires an HTTP or HTTPS proxy for outbound requests. See the Outgoing Proxies section for more information.

Advantages

Custom OAuth integrations provide several advantages:

  • Administrators can provide unified access to multiple OAuth-enabled services through a single interface.
  • Users can programatically and securely access short-lived OAuth tokens without handling sensitive credentials directly.
  • Tokens are automatically refreshed when possible, reducing the need for manual re-authentication.

How custom OAuth integrations differ from advanced integrations

Advanced integrations like Databricks and Snowflake offer ambient credentials, where users arrive in a Workbench session with pre-configured access to the service. CLI tools, SDKs, and libraries automatically detect and use these credentials.

Custom OAuth integrations, on the other hand, provide OAuth tokens that users can leverage programmatically within their sessions. These tokens are made available through R and Python SDKs that communicate with Workbench to retrieve tokens.

OAuth provider configuration

Before configuring Workbench, you must register Workbench as an OAuth client with the service provider you want to integrate.

Registering Workbench as an OAuth client

The exact steps vary by provider, but generally involve:

  1. Create a new OAuth application in your service provider’s developer console or admin interface. This OAuth application must support the OAuth 2.0 authorization code flow.

  2. Set the redirect URI to: https://<your-workbench-url>/oauth_redirect_callback

    Important

    The redirect URI must exactly match your Workbench URL, including the protocol (https://) and any port numbers. The path /oauth_redirect_callback is required.

  3. Configure the application with appropriate scopes and permissions based on what your users need to access.

  4. Record the client credentials (client ID and client secret) provided by the OAuth provider.

  5. Record the authorization and token endpoint URLs for use in Workbench configuration.

  6. Check the token endpoint authentication method in your provider’s documentation (if specified). See Token endpoint authentication methods below for details. If your provider doesn’t specify a method, the default is appropriate in most cases.

Workbench configuration

Workbench supports multiple custom OAuth integrations simultaneously. Configure available integrations in the /etc/rstudio/oauth-clients.conf file.

TipConfiguration Manager

Workbench also provides a web-based Configuration Manager for managing Custom OAuth integrations. See the Administrative Dashboard documentation for details. Deploying changes made through the Configuration Manager will not reload Custom OAuth configurations. You must manually restart the Workbench service for changes to take effect.

Configuration file format

Create or edit the /etc/rstudio/oauth-clients.conf file. For example:

/etc/rstudio/oauth-clients.conf
[box-integration]
name=Box API Access
client-id=your-box-client-id
client-secret=your-box-client-secret
authorization-url=https://account.box.com/api/oauth2/authorize
token-url=https://account.box.com/api/oauth2/token

[custom-api]
name=Company Internal API
client-id=internal-api-client-id
client-secret=internal-api-client-secret
authorization-url=https://api.company.com/oauth/authorize
token-url=https://api.company.com/oauth/token
scopes=read,write

Each [header] names a section with the following properties:

Config Option Description Required (Y/N) Default
name User-friendly display name for this integration No
client-id OAuth client ID from the provider Yes
client-secret OAuth client secret from the provider Yes
token-endpoint-auth-method Method for authenticating with the token endpoint (client-secret-post or client-secret-basic) No client-secret-post
authorization-url OAuth authorization endpoint URL Yes
token-url OAuth token endpoint URL Yes
scopes Comma-separated list of OAuth scopes to request No
Note

If the name property is not specified, Workbench uses the section header (e.g., box-integration) as the display name.

Token endpoint authentication methods

Workbench supports different methods for authenticating with the OAuth token endpoint. Many providers support either method. Check your provider’s OAuth 2.0 documentation for the supported authentication methods, often listed under “token endpoint” or “client authentication” specifications. If your provider’s documentation doesn’t specify a method, the default (client-secret-post) is appropriate in most cases.

POST body authentication (default)

By default, Workbench sends client credentials in the POST body:

token-endpoint-auth-method=client-secret-post

In this configuration, Workbench includes the client_id and client_secret parameters in the body of the token request.

Basic authentication

To use HTTP basic authentication, set:

token-endpoint-auth-method=client-secret-basic

In this configuration, Workbench sends the client ID and secret in the Authorization header using Basic Auth.

Applying configuration changes

After making changes to the configuration file:

  • Restart the Workbench service for changes to take effect:

    sudo rstudio-server restart

Verify the configuration

  1. In your browser, navigate to the Workbench interface and log in.
  2. In the top right corner, click your user name and then Settings.
  3. On the left sidebar, select the Managed Credentials tab.
  4. You should see the configured OAuth integrations listed under the Custom OAuth section.
  5. Click on the Info icon to display and verify details about the integration:
    1. The client ID matches your configuration
    2. The authorization and token endpoint URLs are correct
    3. The scopes are as expected

Security considerations

Client secret protection

  • File permissions: Ensure /etc/rstudio/oauth-clients.conf has restrictive permissions:

    sudo chmod 600 /etc/rstudio/oauth-clients.conf
sudo chown rstudio-server:rstudio-server /etc/rstudio/oauth-clients.conf

  • Version control: Never commit OAuth client secrets to version control systems.

Scope minimization

Configure OAuth scopes to grant only the minimum permissions required:

  • Review each provider’s scope documentation
  • Test integrations with minimal scopes first
  • Gradually add scopes as needed for specific use cases

Token management

  • Workbench automatically handles token refresh when supported by the provider. Refresh token support varies by provider. Some providers require specific scopes (such as offline_access), while others configure this through OAuth application settings. See Refresh token issues for troubleshooting guidance.
  • Users can sign out of integrations through the Managed Credentials settings on the Workbench Homepage (Settings > Managed Credentials). This removes the stored tokens for that integration from Workbench.

Troubleshooting

Common configuration errors

Invalid redirect URI:

  • Verify the redirect URI in your OAuth provider matches exactly: https://<your-workbench-url>/oauth_redirect_callback
  • Check for trailing slashes or incorrect protocols

Client authentication failures:

  • Confirm client ID and secret are correctly copied from the provider
  • Verify the token-endpoint-auth-method matches the provider’s requirements

Network connectivity issues

If your environment uses an HTTP proxy:

  • Configure proxy settings as described in Outgoing Proxies
  • Ensure the proxy allows HTTPS connections to OAuth providers
  • Test connectivity from the Workbench server to OAuth endpoints

Refresh token issues

If tokens are not being automatically refreshed:

  • Check the Workbench database oauth2_tokens table to confirm whether a refresh token was provided by the OAuth provider (note that tokens will only be present after a user has authenticated with the integration in Workbench). See the Data dictionary for more information.
  • If no refresh token is present, check your provider’s documentation for how refresh tokens are enabled. Some providers require specific scopes (such as offline_access), while others configure refresh tokens through OAuth application settings.
  • Verify that the scopes configured in your integration include any required scopes for refresh tokens.
  • If refresh tokens are not included by the provider, users will need to re-authenticate from the Workbench homepage when their access tokens expire.
Back to top