Configuring Connection Details

This section provides instructions for configuring the connection details required to establish communication between your PubSub+ event broker and your third-party system.

PubSub+ Connection Details

The Spring Cloud Stream Binder for PubSub+ uses Spring Boot Auto-Configuration for the Solace Java API to configure its session. In the application.yml, this typically is configured as follows:

solace:
  java:
    host: tcp://localhost:55555
    msg-vpn: default
    client-username: default
    client-password: default

For more information and options to configure the PubSub+ session, see Spring Boot Auto-Configuration for the Solace Java API.

Preventing Message Loss when Publishing to Topic-to-Queue Mappings

If the connector is publishing to a topic that is subscribed to by a queue, messages may be lost if they are rejected (for example, if queue ingress is shut down).

To prevent message loss, configure the reject-msg-to-sender-on-discard option with the including-when-shutdown flag.

Salesforce Connection Details

To manually configure the Salesforce connection details, set the following properties in application.yml:

salesforce:
  pubsub-api-endpoint: <pubsub-api-endpoint>
  pubsub-api-port: 7443
  login-url: "<login_url>"
  auth-flow: < username_password_soap | client_credentials | jwt >

Where:

pubsub-api-endpoint is the endpoint used by the Salesforce Pub/Sub API. For example, the Salesforce Global Endpoint is api.pubsub.salesforce.com. For more information, see Pub/Sub API Endpoints in the Salesforce documentation.
pubsub-api-port is the port used by the Salesforce Pub/Sub API. Allowed values are 7443 and 443.
login-url is the Salesforce login URL (for example, https://<personal_domain>.develop.my.salesforce.com/)
auth-flow is the type of authentication you want to use with Salesforce.

There are additional options you must provide depending on the authentication type you choose. For more information, see Authentication Options.

Authentication Options

The Connector for Salesforce has the following options for authentication:

username_password_soap—Use the legacy username and password authentication with SOAP. For more information, see Salesforce Legacy Username and Password with SOAP.
client_credentials—Use OAuth 2.0 client credentials. For more information, see Salesforce OAuth 2.0 Client Credentials
jwt—Use the OAuth 2.0 JWT Bearer Flow. For more information, see Salesforce OAuth 2.0 JWT Bearer Flow Parameters.

Salesforce Legacy Username and Password with SOAP

To use username and password authentication with SOAP, configure the application.yml file as follows:

auth-flow: username_password_soap
soap:
   username: "<username>"
   password: "<password>"
   security-token: "<security_token>"

Where:

username is the Salesforce username to authenticate with.
password is the password that corresponds to the Salesforce username.
security-token is the security token generated by Salesforce. If you don't have a security token, click your avatar in Salesforce, then click Settings > Reset My Security Token. A new token is emailed to you.

Salesforce OAuth 2.0 Client Credentials

To set up OAuth 2.0 client credentials, use the following configuration:

auth-flow: client_credentials
client-credentials:
  client-id: <salesforce-client-id>
  client-secret: <salesforce-client-secret>

Where:

client-id is the OAuth 2.0 Client ID to authenticate with. The Client ID might appear as "Consumer Key" in Salesforce.
client-secret is the OAuth 2.0 Client Secret. The Client Secret might appear as "Consumer Secret" in the OAuth Settings in Salesforce.

For more information about configuring the OAuth 2.0 Client ID and Client Secret in Salesforce, see Configure a Client Credentials Flow in the Salesforce documentation.

Salesforce OAuth 2.0 JWT Bearer Flow Parameters

To use the OAuth 2.0 JWT Bearer Flow, configure the following properties in application.yml:

auth-flow: jwt
jwt:
  issuer: <issuer>
  audience: <audience>
  subject: <subject>		
  private-key-path: <path-to-key-file>
  private-key-password: <password>

Where:

issuer corresponds to the iss JWT claim. The issuer must contain the OAuth client_id or the connected app for which you registered the certificate.
audience corresponds to the aud JWT claim. The audience identifies the authorization server as an intended audience. Allowed values are:
- https://login.salesforce.com (Default value)
- https://test.salesforce.com
- https://site.force.com/customers (if this connector is authenticating with a Salesforce Experience Cloud site)
subject corresponds to the sub JWT claim. The subject must contain the Salesforce user name to use for authentication.
private-key-path is the file protocol path to the private key file used to sign the JWT. Both unencrypted and encrypted (PKCS #8 and OpenSSL/PEM) private keys are supported. For example:
- For Windows: file:///C:/documents/example.pem
- For Unix/Linux: file:///home/user/documents/example.pem
private-key-password is the password for the private key if it is encrypted.

You must set up a connected app to use JWT. For more information, see Configure a JWT Bearer Flow in the Salesforce documentation.

In addition to following the Salesforce documentation instructions, you must ensure that Plugin Policies are set to Admin approved users are pre-authorized and the user profile/permission set is authorized for the connected app.

You can build and sign a JWT using the template on jwt.io. Change the default text to your client ID and username e-mail, then add your private key to sign the token.

To test your JWT before using it in the connector, issue the following POST request:

POST <YOUR_LOGIN_URL>/services/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=eyJpc3MiOiAiM01WRz...[omitted for brevity]...ZT

Configuring Proxy Support

The Connector for Salesforce supports connecting through HTTP/HTTPS proxies. To configure proxy support, pass the following Java system properties as VM options when you start the connector:

-Dhttp.proxyHost=<proxyhost>
-Dhttp.proxyPort=<proxyport>
-Dhttps.proxyHost=<proxyhost>
-Dhttps.proxyPort=<proxyport>

Where:

http.proxyHost is the hostname or IP address of the HTTP proxy server.
http.proxyPort is the port number of the HTTP proxy server.
https.proxyHost is the hostname or IP address of the HTTPS proxy server.
https.proxyPort is the port number of the HTTPS proxy server.

If your proxy requires authentication, configure it by passing these additional properties:

-Dhttp.proxyUser=<username>
-Dhttp.proxyPassword=<password>
-Dhttps.proxyUser=<username>
-Dhttps.proxyPassword=<password>
-Djdk.http.auth.tunneling.disabledSchemes=""

Where:

http.proxyUser is the username for HTTP proxy authentication.
http.proxyPassword is the password for HTTP proxy authentication.
https.proxyUser is the username for HTTPS proxy authentication.
https.proxyPassword is the password for HTTPS proxy authentication.
jdk.http.auth.tunneling.disabledSchemes="" enables HTTP proxy authentication for HTTPS URLs (required for Oracle JDK 8u111 or later, which disables this feature by default).

For more information on these properties and how to use them, see Java Networking and Proxies in the Oracle Java documentation.

Salesforce Binder Configuration Options

The following properties are available at the Salesforce binder level. These properties are to be prefixed with spring.cloud.stream.salesforce.bindings.<inputname>.consumer. for source bindings and spring.cloud.stream.salesforce.bindings.<outputname>.producer. for target bindings

Salesforce Producer Configuration Options

The following configuration options are available for the Salesforce producers.

Config Option	Type	Valid Values	Default Value	Description
`destination`	`String`	Any	None	The target custom platform event in Salesforce. For example, `/event/<CUSTOM_EVENT_NAME>__e`.

Salesforce Consumer Configuration Options

The following configuration options are available for the Salesforce consumers.

Config Option	Type	Valid Values	Default Value	Description
`destination`	`String`	Any	None	The source of events from Salesforce. For example, Change Data Capture events (`/data/ChangeEvents` and `/data/<OBJECT_NAME>ChangeEvents`) or Custom Events (`/event/<CUSTOM_EVENT_NAME>__e`).
`lvq`	`String`	Any	None	The name of the Last Value Queue (LVQ) on the Solace Transform Processor event broker to use for checkpointing. The Connector for Salesforce stores the last successful Salesforce Replay ID in the LVQ. The LVQ must exist on the same event broker and VPN as the target destination.

Connecting to Multiple Systems

To connect to multiple systems of the same type, use the multiple binder syntax.

For example:

spring: 
  cloud:
    stream: 
      binders:
        
        # 1st solace binder in this example 
     solace1:
          type: solace 
       environment: 
         solace: 
           java:
             host: tcp://localhost:55555
         
     # 2nd solace binder in this example 
     solace2:
          type: solace 
          environment: 
            solace: 
           java:
             host: tcp://other-host:55555
        
     # The only salesforce binder 
     servicebus1:
          type: salesforce
       # Add `environment` property map here if you need to customize this binder. 
       # But for this example, we'll assume that defaults are used.
          
     # Required for internal use 
     undefined:
          type: undefined 
     bindings:
          input-0:
            destination: <input-destination> 
         binder: salesforce1
          output-0:
            destination: <output-destination>
            binder: solace1 # Reference 1st solace binder 
       input-1:
            destination: <input-destination> 
         binder: salesforce1
          output-1:
            destination: <output-destination>
            binder: solace2 # Reference 2nd solace binder

The configuration above defines two binders of type solace and one binder of type salesforce, which are then referenced within the bindings.

Each binder above is configured independently under spring.cloud.stream.binders.<bindername>.environment..

When connecting to multiple systems, all binder configuration must be specified using the multiple binder syntax for all binders. For example, under the spring.cloud.stream.binders.<binder-name>.environment.
Do not use single-binder configuration (for example, solace.java.* at the root of your application.yml) while using the multiple binder syntax.

Provide feedback