Unlock Salesforce Data Cloud: JWT Integration for Server-to-Server & JDBC Access

Vinay Tulluru -

In today's interconnected landscape, securely automating data exchange between systems is paramount. When dealing with Salesforce, especially when accessing the powerful capabilities of Data Cloud, you need a robust and secure method for server-to-server communication. The OAuth 2.0 JWT Bearer Flow is the gold standard, eliminating the need to expose user credentials directly.


This post will help you set up a Salesforce Connected App configured explicitly for the JWT Bearer Flow. This configuration will enable secure server-to-server integrations and allow external tools (like DBeaver, SQL Workbench/J, or custom applications) to connect to your Salesforce Data Cloud instance using a standard JDBC connection, leveraging JWT authentication.

Let's dive into the steps!

Prerequisites


Before we start, ensure you have:

1. Salesforce Admin Access: You'll need permissions to create and manage Connected Apps and assign user permissions.
2. OpenSSL (or similar tool): Required to generate the private key and public certificate pair needed for JWT signing.
3. Understanding of OAuth 2.0: Familiarity with the basic concepts will be helpful.
4. A Dedicated Integration User (Recommended): While you can use an existing admin user, creating a dedicated user profile/permission set for integrations with the principle of least privilege is best practice.

Steps


Step 1: Generate a Private Key and Public Certificate

The JWT flow relies on asymmetric cryptography. Your external application will sign a JWT using a private key, and Salesforce will verify this signature using the corresponding public certificate.

Use OpenSSL to generate these files:

# Generate a private key (keep this secure!)
openssl genrsa -out SalesforceDataCloud_private.key 2048

# Generate a certificate signing request (CSR)
openssl req -new -key SalesforceDataCloud_private.key -out SalesforceDataCloud.csr
# (You'll be prompted for details - fill them appropriately, common name matters less here)

# Generate a self-signed public certificate (valid for 365 days)
openssl x509 -req -days 365 -in SalesforceDataCloud.csr -signkey SalesforceDataCloud_private.key -out SalesforceDataCloud_certificate.pem

You now have:

  • SalesforceDataCloud_private.key: Your private key. Protect this file carefully! Your server/application will use it.
  • SalesforceDataCloud_certificate.pem: Your public certificate. You will upload this to Salesforce.

Step 2: Navigate to Salesforce App Manager.

  1. Log in to your Salesforce org.
  2. Go to Setup.
  3. Type App Manager in the Quick Find box and select App Manager.

Step 3: Create a New Connected App

  1. In the App Manager, click the New Connected App button in the top right corner. (See screenshot Step 12).
  2. You might see a choice between "Create a Connected App" and "Create an External Client App". For this JWT + Data Cloud JDBC use case, choose Create a Connected App and click Continue. (See screenshot Step 12). Note: External Client Apps are newer and often used for Headless flows, but the traditional Connected App fully supports JWT.
  3. If prompted about changes taking time, click Continue.

Step 4: Configure Basic Information

Fill in the required basic information:

  • Connected App Name: Something descriptive, e.g., Data Cloud JDBC JWT Integration.
  • API Name: This will auto-populate (e.g., Data_Cloud_JDBC_JWT_Integration).
  • Contact Email: Enter a valid email address.
  • (Optional) Add a Logo and Icon URL if desired.

Step 5: Enable and Configure OAuth Settings

This is the core configuration section.

  1. Scroll down to the API (Enable OAuth Settings) section.
  2. Check the box Enable OAuth Settings.
  3. Callback URL: For the JWT Bearer flow (server-to-server), the callback URL isn't strictly used in the same way as 3-legged flows. However, it's required. You can enter a placeholder like https://login.salesforce.com/services/oauth2/callback or http://localhost:1717/OauthRedirect or use a debug tool URL like https://oauthdebugger.com/debug.
  4. Check the box Use digital signatures.
  5. Click Choose File and upload the public certificate file (SalesforceDataCloud_certificate.pem) you generated earlier. (See screenshots Step 6 & Step 4 showing file selection).

Step 6: Select Required OAuth Scopes

OAuth scopes define what permissions this Connected App has when it authenticates. Select the necessary scopes from "Available OAuth Scopes" and move them to "Selected OAuth Scopes" using the "Add" arrow. For Data Cloud JDBC access and general API interaction, you'll typically need:

  • Access and manage your data (api)
  • Perform requests on your behalf at any time (refresh_token, offline_access) (Essential for server-to-server where the app needs to get new tokens without user interaction)
  • Manage Data Cloud Calculated Insight data (cdp_calculated_insight_api)
  • Manage Data Cloud Identity Resolution (cdp_identityresolution_api)
  • Manage Data Cloud Ingestion API data (cdp_ingest_api)
  • Manage Data Cloud Profile data (cdp_profile_api)
  • Perform ANSI SQL queries on Data Cloud data (cdp_query_api) (Crucial for JDBC access!)
  • Access Interaction API resources (interaction_api) (Often needed alongside Data Cloud)
  • Access all Data Cloud API resources (cdp_api) (Alternatively, a broader scope if needed, but specific scopes are better practice).

Step 7: Enable JWT Flow Specific Settings

Ensure the JWT flow itself is enabled:

  1. Scroll down further within the API (Enable OAuth Settings) section.
  2. Make sure the checkbox Issue JSON Web Token (JWT)-based access tokens for named users is checked. (See senshot ). This is the explicit switch for the JWT flow where the app impersonates a specific user.
  3. (Optional but often relevant) You might see Enable Client Credentials Flow. This is another server-to-server flow, but different from JWT. For this guide, we are focusing on JWT. 

Step 8: Save the Connected App & Get Consumer Key

  1. Scroll to the bottom (or top) and click Save. (See screenshot below).
  2. It might take a few minutes (up to 10) for the changes to fully propagate across Salesforce. Click Continue on the confirmation page.
  3. You'll be taken to the detail page for your new Connected App. Locate the Consumer Key under the API (Enable OAuth Settings) section. Copy this value and store it securely. This is the client_id or issuer (iss claim) for your JWT. (See screenshot).
💡
Note: The Consumer Secret is also displayed here. While not directly used for signing in the JWT flow itself (the private key handles that), keep it secure as it might be needed for other flows or initial setup depending on the client library.

Step 9: Manage Policies - Pre-authorize Users

For server-to-server flows, you don't want users to be prompted for approval. You need to pre-authorize the profiles or permission sets that are allowed to use this Connected App.

  1. From the Connected App detail page, click the Manage button (or navigate back to App Manager, find your app, and click Manage from the dropdown). (See screenshot Step 14 showing the Manage link).
  2. On the management page, click Edit Policies. (See screenshot below).
  3. Under OAuth Policies, change the Permitted Users dropdown from "All users may self-authorize" to Admin approved users are pre-authorized. (See screenshot Step 16).
  4. Acknowledge the warning message about access potentially being denied until profiles/permission sets are added. Click OK. (See screenshot below).

Step 10: Specify the 'Run As' User for JWT

Crucially for the "Issue JWT for named users" setting, you need to tell Salesforce which user the JWT represents (the sub or subject claim in the JWT). This user's permissions will determine what the integration can do.

  1. While still on the Edit Policies page, scroll down towards the Client Credentials Flow or JWT-Based Access Token Settings for Named Users section (the exact location might vary slightly).
  2. Find the Run As lookup field (or similar, sometimes labelled under JWT-Based Access Token Settings for Named Users or potentially shared with Client Credentials Flow if that was also enabled).
  3. Select the dedicated integration user (or the appropriate user) that this application will impersonate. (See screenshot below highlighting the "Run As" lookup).
  4. Click Save at the bottom of the policies page. (See screenshot below).

Step 11: Assign Profiles / Permission Sets

Now that you've set the app to require admin approval, you must grant that approval.

  1. Go back to the main management page for the Connected App (Click Manage Connected Apps link if needed, then click your app name). (See screenshot below).
  2. Scroll down to the Profiles and Permission Sets related lists. (See screenshot below).
  3. Click Manage Profiles (or Manage Permission Sets).
  4. Select the Profile(s) (e.g., 'System Administrator' or your custom integration profile) or Permission Set(s) associated with the user you selected in the "Run As" step, and which should be allowed to use this Connected App. (See screenshot Step 19 showing System Administrator added).
  5. Click Save.

Connecting via JDBC using JWT

Now that the Connected App is configured:

  1. Your external application or JDBC tool (like DBeaver) needs to support OAuth 2.0 JWT Bearer Token Authentication.
  2. You will not use a standard username and password when configuring the connection. Instead, you'll typically provide:
    • Consumer Key: The value you copied in Step 8 (used as client_id and often the iss claim).
    • Username: The username of the Salesforce user you selected in the "Run As" step (used as the sub claim).
    • Private Key: The content of your SalesforceDataCloud_private.key file (or the path to it, depending on the tool).
    • Authentication Endpoint/URL: Usually https://login.salesforce.com/services/oauth2/token (or your My Domain URL if applicable, used as the aud claim).
    • JDBC URL: This will be specific to the Salesforce Data Cloud JDBC driver, often looking something like jdbc:salesforce:dataCloud://<YourSalesforceDomain>.my.salesforce.com?useJwt=true&... (Consult the specific driver documentation for the exact format and parameters).

The application/tool will use these details to construct the JWT, sign it with the private key, and exchange it with the Salesforce token endpoint for an access token. This token, carrying the scopes you defined (cdp_query_api, etc.), allows the JDBC driver to execute queries against Data Cloud.

Conclusion

You've successfully configured a Salesforce Connected App for secure server-to-server integration using the JWT Bearer Flow! This setup provides a high level of security by eliminating the need for stored credentials. It allows authorized applications to interact with Salesforce APIs, including querying Data Cloud via JDBC, under the context of a pre-approved user. Please remember to protect your private key and regularly review the permissions granted via OAuth scopes and profiles/permission sets.

Happy integrating!