Salesforce

Enhanced Advanced

The Salesforce integration allows content running on Posit Connect to access the Salesforce API, either as the content viewer or as a designated Salesforce integration user.

Component parts of the Salesforce integration.
Component part Value
Provider registration An External Client App in Salesforce, with OAuth enabled globally and on the app
Authentication types Viewer, Service Account
Configuration auth_type, auth_mode, sf_host_domain, client_id, client_secret (sensitive), scopes
Credential delivery Token exchange
Content compatibility Viewer: interactive only. Service Account: interactive and rendered.

Provider registration

Performed by a Salesforce administrator.

Enable OAuth settings for API integration in Salesforce

The Salesforce administrator registers an External Client App in Salesforce and enables OAuth both globally and on the External Client App.

Once the Salesforce administrator has registered an external client app, they can configure the app under the “OAuth Settings” dropdown. Allowed scopes for the OAuth application are set here.

The Salesforce administrator must also configure a Callback URL for the external client app under OAuth Settings > App Settings.

The Callback URL is defined as https://connect.example.org/__oauth__/integrations/callback. Replace connect.example.org with the address of the Connect server.

Viewer integrations

Confidential apps

When using Confidential authentication, the Connect Administrator must obtain the client ID and client secret, referred to as the consumer key and consumer secret within Salesforce, from the Salesforce administrator. This information is available under OAuth Settings > App Settings.

Public apps

If your Salesforce infrastructure is in a secure environment and your Salesforce administrator would prefer to use Public authentication then the External Client App within Salesforce must not have “Require secret for Web Server Flow” and “Require secret for Refresh Token Flow” set within the External Client App OAuth Settings. Please see the Salesforce OAuth Settings documentation for details.

Service account integrations

Salesforce also supports the OAuth 2.0 Client Credentials Flow, which maps onto Service Account integrations in Connect.

To support Salesforce Service Account integrations in Connect, the Salesforce administrator must perform additional configuration of the OAuth app in Salesforce.

First, under Settings > OAuth Settings > Flow Enablement, the Salesforce Administrator should check the box for “Enable Client Credentials Flow”.

This enables a new “Enable Client Credentials Flow” option under Policies > OAuth Policies > OAuth Flows and External Client App Enhancements. The Salesforce Administrator should enable this option, and select the “integration user” which will be identified by the returned credentials.

Transfer information to Connect administrator

The Salesforce administrator shares the following information with the Connect administrator:

Field Description
sf_host_domain The host domain for your Salesforce environment.
client_id The Consumer Key found under OAuth Settings > App Settings > Consumer Key and Secret.
client_secret The Secret found under OAuth Settings > App Settings > Consumer Key and Secret. Not required for Public Viewer integrations.
scopes Permissions supported by the OAuth application. Only include scopes required by Connect. Not required for Service Account integrations.

Authentication types

This integration supports the Viewer and Service Account authentication types.

The Salesforce implementation of the OAuth 2.0 Client Credentials Flow, which backs the Service Account authentication type, differs slightly from other providers. Note the following properties when configuring a Service Account integration against Salesforce:

  • Salesforce does not accept scopes as a parameter in the token exchange request. The expected scopes are instead assigned to the connected app. This is why there is no “scope” field when configuring the integration in Connect. Instead, scopes must be configured by the Salesforce Administrator.
  • Salesforce requires specifying an “integration user” which is identified by the returned access token. Depending on how the Salesforce environment is configured, this can be a named user instead of a machine account. All applications hosted on Connect that use a Salesforce Service Account integration execute in Salesforce using the identity of the integration user.

Connect configuration

Performed by a Connect administrator.

Create the integration in Connect

Using the information from the Salesforce 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 Viewer Salesforce integration using curl and the Connect Server API.

Note

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": "salesforce",
    "name": "Salesforce integration",
    "description": "A helpful description for publishers to use when choosing an integration for their content.",
    "config": {
      "auth_mode": "Confidential",
      "auth_type": "Viewer",
      "client_id": "<client-id>",
      "client_secret": "<client-secret>",
      "scopes": "refresh_token offline_access api web",
      "sf_host_domain": "<sf_host_domain>"
    }
  }'
# 200 OK
# {"guid": "<oauth-integration-guid>", ... }

Credential delivery

Content receives a Salesforce 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.

See Token exchange for the general mechanism.

Publisher usage

Once the integration is configured, publishers can use it in their content. See the following cookbook recipes for examples:

Viewer integrations:

Service account integrations: