Skip to main content

Salesforce Setup

1. Create a Connected App​

In Setup → App Manager → New Connected App:

  1. Enable OAuth Settings.
  2. Add the scopes Manage user data via APIs (api) and, for real-time streaming, Perform requests at any time (refresh_token, offline_access).
  3. Note the Consumer Key and Consumer Secret.

2. Choose an OAuth flow​

  1. On the Connected App, enable Client Credentials Flow.

  2. Assign a Run As user — use a dedicated, API-Only integration user. This is set separately from the app itself: Setup → Manage Connected Apps → your app → Edit Policies → Client Credentials Flow → Run As. Until it is set, token requests fail with invalid_grant: no client credentials user enabled.

  3. Check the flow before configuring Kafka (a new app can take a few minutes to become usable):

    curl -s https://YOUR_DOMAIN.my.salesforce.com/services/oauth2/token \
    -d grant_type=client_credentials -d client_id="$KEY" -d client_secret="$SECRET"

    If your org no longer allows new connected apps, create an External Client App with the same OAuth settings and client credentials flow.

  4. Configure the connector with:

sf.auth.grant.type=client_credentials
sf.instance.url=https://YOUR_DOMAIN.my.salesforce.com
sf.consumer.key=...
sf.consumer.secret=...
My Domain required

login.salesforce.com and test.salesforce.com are not valid for the Client Credentials flow. sf.instance.url must be the org's My Domain URL. The connector rejects the login hosts at config-validation time.

  1. Generate an RSA key pair and upload the X.509 certificate to the Connected App (Use digital signatures).
  2. Pre-authorize the integration user's profile or permission set.
  3. Configure:
sf.auth.grant.type=jwt_bearer
sf.instance.url=https://YOUR_DOMAIN.my.salesforce.com
sf.consumer.key=...
sf.username=integration@yourcompany.com
sf.jwt.keystore.path=/secrets/sf-private-key.pem

sf.jwt.keystore.path accepts a PEM (PKCS#8) private key, a JKS, or a PKCS12 keystore (sf.jwt.keystore.password for the latter two). No refresh token is issued — the connector re-mints the JWT automatically on expiry.

Username-Password (legacy — avoid)​

Supported for old orgs only (sf.auth.grant.type=password plus sf.username, sf.password, sf.password.token). Salesforce blocks this flow by default in orgs created Summer '23 or later; migrate to one of the flows above.

3. Enable Change Data Capture (source connector)​

In Setup → Change Data Capture, add each object you plan to stream (e.g. Account, Contact, Opportunity). Each selected entity publishes to its own channel (/data/AccountChangeEvent, ...), which the source connector subscribes to per SObject.

tip

CDC events are retained for 72 hours. Restarts within that window resume exactly where they left off; longer outages trigger the connector's gap recovery.

4. Platform Events (source and Platform Event sink)​

Both directions work with an existing platform event definition. Create it under Setup → Platform Events — only Checkbox, Date, Date/Time, Number, Text, and Text Area (including long text area) field types exist on platform events.

  • Streaming events into Kafka (sf.platform.events on the source connector): give the integration user Read access to the event in its permission set (Object Settings). Events are retained for 72 hours, like CDC.
  • Publishing from Kafka (Platform Event sink): the integration user needs Create access to the event.