Custom

Enhanced Advanced

The Custom integration communicates with any external system that implements the OAuth 2.1 authorization code (Viewer) or client credentials (Service Account) flow. Use it when Posit Connect does not provide a first-class integration for the provider you need.

Component parts of the Custom integration.
Component part	Value
Provider registration	An OAuth application in any OAuth 2.1 provider
Authentication types	Viewer, Service Account, Workload Identity
Configuration	Viewer and Service Account: `auth_type`, `auth_mode`, `client_id`, `client_secret` (sensitive), `authorization_uri`, `token_uri`, `token_endpoint_auth_method`, `scopes`, `use_pkce`. Workload Identity: `auth_type`, `audience`, `subject`
Credential delivery	Token exchange
Content compatibility	Viewer: interactive only. Service Account and Workload Identity: interactive and rendered.

Provider registration

Performed by an OAuth provider administrator.

Create an application in the OAuth provider

Register application

The administrator of the OAuth provider must register Connect as an application before an integration can be configured.

Viewer Integration

The administrator adds a redirect_uri for the OAuth application as seen in the screenshot below. The OAuth provider sends the user credentials to the redirect_uri at the end of the OAuth handshake, allowing Connect to obtain a temporary access token and refresh token.

The OAuth application is configured with the following redirect URL (sometimes referred to as a callback URL): https://connect.example.org/__oauth__/integrations/callback. 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.

Service Account Integration

Service account integrations do not direct the user through a login flow, so a redirect_uri is not required.

Transfer information to Connect administrator

The administrator of the OAuth provider shares the following information with the Connect administrator:

Field	Description
`client_id`	Unique identifier for the OAuth application.
`client_secret`	Secret identifier for the OAuth application. Not required for Public Viewer integrations.
`authorization_uri`	The URI for the authorization endpoint. Can also be obtained from the Authorization Server Metadata Endpoint.
`token_uri`	The Uniform Resource Identifier (URI) for the token endpoint. Can also be obtained from the Authorization Server Metadata Endpoint.
`token_endpoint_auth_method`	Determines how parameters are passed to the OAuth application. This is a property of the OAuth application itself.
`scopes`	The permissions requested by Connect.

Authentication types

Ensure the proper authentication type is selected for the type of credentials that will be retrieved from the OAuth provider. See the documentation on supported authentication types for more information.

The Custom integration is also the escape hatch for behavior the first-class integrations do not expose. In particular, it is the only way to disable Proof Key for Code Exchange (PKCE) for a non-AWS provider that cannot support it.

Connect configuration

Performed by a Connect administrator.

Create the integration in Connect

Using the information from the OAuth provider administrator, the Posit Connect administrator creates an integration through the dashboard’s System > Integrations settings. Once the integration has been created in Connect, it is available for use by all publishers. See Access control lists for information on customizing access to specific users or groups.

Alternatively, the example below shows how to create a Confidential Custom integration using curl and the Connect Server API. Replace connect.example.org with the address of the Connect server.

Terminal

curl -H "Authorization: Key ${CONNECT_API_KEY}" \
  -XPOST https://connect.example.org/__api__/v1/oauth/integrations \
  --data '{
    "template": "custom",
    "name": "Custom integration",
    "description": "A helpful description for publishers to use when choosing an integration for their content.",
    "config": {
      "auth_type": "Viewer",
      "auth_mode": "Confidential",
      "client_id": "<client-id>",
      "client_secret": "<client-secret>",
      "authorization_uri": "<authorization-endpoint>",
      "token_uri": "<token-endpoint>",
      "scopes": "offline_access openid profile email"
    }
  }'
# 200 OK
# {"guid": "<oauth-integration-guid>", ... }

Note

integrations in Connect use the PKCE (Proof Key for Code Exchange) extension for the authorization code flow by default. PKCE is required in the upcoming OAuth 2.1 specification, and is recommended in all cases to protect against authorization code injection attacks. If necessary, PKCE can be disabled by creating a Custom integration with "use_pkce": false in the config map, but this is not recommended.

Credential delivery

Content receives an OAuth access token through the Connect credential exchange endpoint, using the viewer’s user session token for Viewer integrations or the content session token for Service Account integrations. Refresh tokens are never delivered to content.

See Token exchange for the general mechanism.

Publisher usage

See the Integrations section of the Connect User Guide for Python and R examples of obtaining and using an access token.