OAuth Integrations
This section describes how to use OAuth integrations in Posit Connect. OAuth integrations allow content publishers to securely access short-lived OAuth access tokens with limited permissions. Using an OAuth access token in published content is more secure than embedding long-lived credentials (like Personal Access Tokens) when accessing protected resources in an external system, like Azure, Databricks, or Snowflake.
Access tokens are issued to Connect by an 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 in a single source and delegate those permissions to Connect. Delegated permissions coming from a single source of truth are less likely to fall out-of-sync than coordinating permission rules across many published apps.
OAuth integration types
Authentication types
Viewer
By default, all OAuth integrations in Connect use the Viewer authentication type, which implements the OAuth 2.0 Authorization Code Grant Type. Viewer OAuth integrations provide content publishers with an OAuth access token which represents the identity of the content viewer. This allows content to access protected resources on behalf of the viewer, providing a personalized experience when interacting with deployed content on Connect.
When deployed content is configured to use a Viewer OAuth integration, 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 the viewer consents, they are redirected to the content running in Connect. The content then uses the viewer’s credentials when making requests that require access to protected resources.
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.
Service account
Some OAuth integrations support the Service Account authentication type, which implements the OAuth 2.0 Client Credentials Grant Type. Service Account OAuth integrations provide content publishers with an OAuth access token which represents a service account identity configured in the external system, rather than a specific viewer. This allows content to access protected resources using the service account identity, which will provide the same experience for all users when viewing deployed content on Connect.
Importantly, this service account identity is curated and maintained by Connect, rather than the content item itself. This means that Connect admins have a centralized source-of-truth for sensitive credentials which is auditable. Service account credentials are easily revoked or rotated by Connect admins.
Security considerations
All publishers are able to access all OAuth integrations configured on the Connect Server. This has different implications for each authentication type.
For Viewer OAuth integrations, because permissions are defined by the external system and not Connect, the viewer must have been granted access to the external system in order to use the integration at all. The access provided to the integration is implicitly restricted by the external system.
For Service Account OAuth integrations, all publishers and viewers will have access to the Service Account’s identity and its affiliated permissions in the external system.
Additional security details and considerations are provided in the OAuth Integrations Security Documentation.
Supported content types
OAuth integrations which use Viewer authentication only support interactive content. OAuth integrations which use Service Account authentication support interactive and rendered content.
Static content is not supported by OAuth integrations.
| Auth Type | Interactive | Rendered | Static |
|---|---|---|---|
| Viewer | Yes | No | No |
| Service Account | Yes | Yes | No |
Supported access patterns
Public access (No login required) and Share Links are not supported for Viewer integrations. Both content access patterns are are supported for Service Account integrations.
| Auth Type | Public Access | Share Links |
|---|---|---|
| Viewer | No | No |
| Service Account | Yes | Yes |
First-class vendor support
Connect provides first-class OAuth integrations against many popular third-party vendors. If a third-party vendor is not natively supported by Connect, the Custom OAuth integration type can be used to communicate with any external system that implements OAuth 2.0.
All OAuth integration types support Viewer authentication. Service Account authentication is conditionally supported by some types of integrations.
| Integration Type | Viewer | Service Account |
|---|---|---|
| Azure | Yes | Yes |
| Custom | Yes | Yes |
| Databricks | Yes (default) | No |
| GitHub | Yes (default) | No |
| Yes (default) | No | |
| Salesforce | Yes (default) | No |
| Snowflake | Yes (default) | No |
Configuring and using an OAuth integration
Personas
To configure and use an OAuth integration in Connect, the following personas are required:
- OAuth application administrator - creates an OAuth application in an external system.
- Connect administrator - creates an OAuth integration in Connect.
- Connect publisher - authors the content which accesses protected resources. 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.
Persona responsibilities
The following section describes the responsibilities of each persona needed to configure and use an OAuth integration in Connect. The role of each persona is ordered chronologically, but some personas may overlap as they communicate information back-and-forth.
OAuth application administrator
The OAuth application administrator in the external system registers a new OAuth application that can issue OAuth tokens to Connect.
If the Connect OAuth integration uses Viewer authentication, the OAuth application administrator configures the application with the following redirect URL (sometimes referred to as a callback URL): https://connect.example.org/__oauth__/integrations/callback, replacing connect.example.org with the address of the Connect server.
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 and Service Account OAuth integrations. 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.
Salesforce OAuth integrations require the following additional field(s):
sf_host_domain- The Salesforce host domain.
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.
Connect administrator
The Connect administrator creates a new OAuth integration using the dashboard or the Connect Server API.
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:
Connect publisher
The Connect publisher associates the OAuth integration with their content using the dashboard or the Connect Server API. 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.
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. If the integration uses the Viewer authentication type, a login button is also provided.
Connect viewer
If the OAuth integration uses the Viewer authentication type, Connect users who have the Viewer permission on the content item receive a personalized view when they visit the deployed application.
If the OAuth integration uses the Service Account authentication type, the content will execute for all users who have the Viewer permission using the OAuth credentials of the service account identity. Content will execute identically for each viewer.