OAuth Integrations

Enhanced Advanced

This section describes how to use OAuth integrations in Posit Connect. OAuth integrations allow content publishers to access the viewer’s temporary OAuth credentials securely. OAuth access tokens are short-lived and have a limited set of permissions, making them more secure than using a long-lived Personal Access Token (PAT). These credentials are used by the deployed content to access protected resources on behalf of the viewer, providing a personalized experience when interacting with deployed content on Connect.

Posit Connect supports integrating with external systems using OAuth access tokens. Access tokens are issued to Connect by the external system and are used to access protected resources. Access controls for the protected resource are defined by the external system, not by Connect. This allows administrators of the external system to create fine-grained access controls for their users and delegate those permissions to Connect without needing to worry about those permissions becoming out-of-sync.

To configure and use an OAuth integration in Posit Connect, the following personas are required:

• OAuth application administrator - creates the OAuth application in the external system.
• Connect administrator - creates an OAuth integration in Posit Connect.
• Connect publisher - authors the content which accesses protected resources as the content viewer. For more information on authoring content that accesses protected resources, see the OAuth Integrations section of the User Guide.
• Connect viewer - views the deployed content on Connect. On visiting the deployed content for the first time, the viewer must grant consent for the content to use their credentials when accessing protected resources.

Note

OAuth integrations are only supported for interactive content types. Static and rendered content do not currently support OAuth integrations.

Public access (Anyone - no login required) content and private links are also not supported.

Overview

When deployed content is configured to use an OAuth integration, the content viewer’s access token is requested using the Authorization Code Grant Type. This allows Posit Connect to request a temporary token from the OAuth application. The content viewer is redirected to a consent screen after visiting the content for the first time. The viewer must explicitly grant Connect permission to access the protected resources on their behalf.

Once consent is granted, the viewer is redirected to the content running in Connect. The content then uses the viewer’s credentials when making requests that require access to protected resources.

Warning

Assuming the content viewer has granted consent after visiting the content for the first time, the publisher has access to the viewer’s OAuth token. Content publishers who use OAuth integrations are responsible for keeping the viewer’s OAuth token secure. Publishers should not attempt to store or cache the OAuth token in any way. Only the access token (short-lived, scoped permissions) is exposed to the publisher. OAuth refresh tokens are never exposed to the publisher.

Using an OAuth integration

The OAuth application administrator registers an OAuth application

The OAuth administrator registers a new OAuth application so that the external system can issue OAuth tokens to Posit Connect. The OAuth application is configured with the following redirect URL (sometimes referred to as a callback URL): https://connect.example.org/__oauth__/integrations/callback.

Note

Replace connect.example.org with the address of the Connect server.

Note

For OAuth application administrators who prefer to use the same OAuth application for both Posit Connect and Posit Workbench, simply register the Workbench redirect URL (https://workbench.example.org/oauth_redirect_callback) in addition to the Connect redirect URL.

Once the OAuth application is registered, the OAuth administrator provides the following information to the Connect administrator:

• client_id (required) - The client ID identifies the OAuth application.
• client_secret (optional) - Required for Confidential OAuth applications. Sometimes referred to as an app password.
• scopes (optional) - A list of allowed OAuth scopes (permissions) that can be requested.

There are additional fields that are required depending on the type of OAuth integration being created. See the associated documentation for each type of integration for details on how to register a new OAuth application.

Azure OAuth integrations require the following additional field(s):

• tenant_id - The unique identifier of the organization in Microsoft Entra ID.

Databricks OAuth integrations require the following additional field(s):

• workspace_host - The hostname of the Databricks workspace.

GitHub OAuth integrations only require a client ID and a client secret.

Google OAuth integrations only require a client ID and a client secret.

Snowflake OAuth integrations require the following additional field(s):

• account_url - The Snowflake account URL.

Custom OAuth integrations require the following additional field(s):

• authorization_uri - The Authorization Endpoint of the OAuth application.
• token_uri - The Token Endpoint of the OAuth application.

The Connect administrator creates a new integration

The Connect administrator creates a new OAuth integration using the dashboard or the Connect Server API.

Note

Once an OAuth integration is created in Connect, it is available for use by all publishers for their content. Because the permissions are defined by the external system, not Connect, the viewer must have been granted access to the external system in order to use the integration. Thus, there is no need for Connect to limit publisher’s access to the OAuth integration in Connect.

For instructions on how to configure and use a specific type of OAuth integration, see the associated documentation. The following types of OAuth integrations are supported:

• Azure
• Databricks
• GitHub
• Google
• Snowflake
• Custom

The publisher associates the integration with their content

The Connect publisher associates the OAuth integration with their content using the dashboard or the Connect Server API.

Note

For more information about authoring content that uses OAuth integrations, see the OAuth Integrations section of the User Guide.

The example below uses curl and the Connect Server API to associate the integration created in the previous step to an existing piece of deployed content in Connect.

Note

Replace connect.example.org with the address of the Connect server.

Terminal

curl -H "Authorization: Key ${CONNECT_API_KEY}" \
  -XPUT https://connect.example.org/__api__/v1/content/<content-guid>/oauth/integrations/associations \
  --data '[
    {"oauth_integration_guid": "<oauth-integration-guid>"}
  ]'

Alternatively, the Connect publisher associates the OAuth integration with their content through the Access tab in the content settings pane of the dashboard, where they will see an Integrations section with an Add integration button.

Clicking this button will open a modal which allows the Connect publisher to select an OAuth integration.

After selecting an integration and saving, the Add integration button is replaced with a panel containing information about the integration and a button to log in to the OAuth Integration.

The viewer visits the content URL to view the content

Connect users who have the Viewer permission on the content item receive a personalized view when they visit the deployed application.