Salesforce Connector: JWT Bearer Authentication

This guide covers JWT Bearer (API-Only) authentication only. For the Credentials and OAuth2 methods, refer to Salesforce connection.

JWT Bearer is a server-to-server login that requires no browser and works with API-only Integration licenses, making it suitable for unattended, scheduled integrations. Complete the Salesforce-side setup in Part 1 and Part 2, then use the resulting values to configure the connection in Data Integration in Part 3. If you encounter the error grant type not supported, go directly to Troubleshooting.

Prerequisites

• System Administrator access to the Salesforce org (Production or Sandbox).
• An integration user account that is active and has the API Enabled permission. This can be an API-only Integration license user.
• OpenSSL, or an equivalent tool, to generate a certificate and private key.

Part 1: Generate the certificate and private key

Run the following command once, on any machine, to create a matching key pair: a private key that you keep, and a certificate that you upload to Salesforce.

openssl req -x509 -sha256 -nodes -days 730 -newkey rsa:2048 -keyout server.key -out server.crt

• server.key: The private key. Upload this file to Data Integration. Never upload it to Salesforce, and never email or log it.
• server.crt: The certificate. Upload this file to Salesforce. It must be 4 KB or smaller.

note

Salesforce stores only the certificate (the public key). Data Integration signs each login request with the private key, and Salesforce verifies that signature using the certificate. The private key and the uploaded certificate must come from the same generated pair, or authentication fails.

Part 2: Create and configure the connected app

Create the app

1. In Salesforce, navigate to Setup > App Manager > New External Client App.
2. Enter a connected app name, API name, and contact email.
3. Select Enable OAuth Settings.
4. Enter a Callback URL. Salesforce requires a value in this field, but the JWT Bearer flow does not use it. Enter a placeholder such as https://login.salesforce.com.

Enable the JWT Bearer flow

1. Select Enable JWT Bearer.
2. Click Choose File and upload server.crt, the certificate you generated in Part 1. Do not upload the .key private key file here.

important

The JWT Bearer grant type is accepted only for a connected app that has both Enable OAuth Settings and digital signatures enabled with a certificate uploaded. If digital signatures are not enabled, or if only the private key was uploaded, Salesforce rejects the grant with error=unsupported_grant_type ("grant type not supported"). This is the most common cause of that error.

Select OAuth scopes

Under Selected OAuth Scopes, add both of the following:

• Manage user data via APIs (api), also shown as "Access and manage your data (api)."
• Perform requests at any time (refresh_token, offline_access).

Save and copy the Consumer Key

1. Click Create, then Continue. Salesforce can take 2–10 minutes to make a new or edited connected app usable. Testing immediately can produce transient errors.
2. Open the app, select Settings, then Manage Consumer Details (verify by email if prompted), and copy the Consumer Key. You provide this value when you configure the connection in Data Integration.

Pre-authorize the integration user

The JWT Bearer flow has no interactive consent step, so you must approve the integration user in advance.

1. On the connected app, go to Manage > Edit Policies.
2. Set Permitted Users to Admin approved users are pre-authorized.
3. Set IP Relaxation to Relax IP restrictions, or add Data Integration's IP ranges.
4. Click Save.
5. Assign the integration user to the app through a profile or permission set, either from the app's Profiles/Permission Sets related list, or from the permission set's Assigned Connected Apps list.

warning

If you skip this step, the connection succeeds only after you fix the certificate configuration, then fails with a different error: invalid_grant: user hasn't approved this consumer. That error means the integration user is not pre-authorized.

Part 3: Configure the connection in Data Integration

Create a Salesforce connection and select JWT Bearer (API-Only) as the credentials type. Refer to Establishing a Salesforce connection for the full connection creation procedure. Enter the following values:

Field	Value
Credentials Type	JWT Bearer (API-Only)
Environment Type	Production or Sandbox. This setting determines the token audience: Production uses the login endpoint, and Sandbox uses the test endpoint.
Consumer Key	The Consumer Key copied from the connected app.
Integration Username	The pre-authorized integration user, for example integration@company.com.
Private Key (PEM)	Upload server.key, renamed with a .pem extension. Upload the private key, not the .crt certificate.
Audience (optional)	Leave blank unless My Domain is enforced for token requests. If it is, enter your My Domain URL.

Click Test Connection. A successful test returns an access token and instance URL. This flow does not use a refresh token by design; Data Integration re-mints the token automatically when it expires.

Troubleshooting

Error: "Salesforce JWT authentication failed: grant type not supported"

Salesforce returns error=unsupported_grant_type. This indicates a Salesforce configuration issue, not a Data Integration issue; the connector sends the request correctly. Check the following in order:

1. Digital signatures are enabled with a certificate. On the connected app, confirm Use digital signatures is selected and server.crt is uploaded. See Enable the JWT Bearer flow. This is the usual fix, since the JWT grant type is allowed only for an app configured for digital signatures.
2. You uploaded the certificate, not the private key. Salesforce requires server.crt. If you uploaded a private key or PEM file instead, re-upload the .crt file. Keep the private key in Data Integration only.
3. Allow time for propagation. A newly created or edited connected app can take 2–10 minutes to become active. Retry after a short wait.
4. The certificate is on the correct object. Upload the certificate on the connected app itself, not in Certificate and Key Management, and not on a different app.
5. OAuth scopes are configured. Confirm the api and refresh_token, offline_access scopes are selected. See Select OAuth scopes.

Other errors

Salesforce error	Cause and fix
invalid_grant: user hasn't approved this consumer	The integration user is not pre-authorized. Complete Pre-authorize the integration user: set Permitted Users to Admin approved users are pre-authorized, and assign the user through a profile or permission set.
invalid_grant with an audience-related message	The connection uses the wrong environment. Production must use login.salesforce.com; Sandbox must use test.salesforce.com. Check the Environment Type setting in Data Integration, or set the Audience override to your My Domain URL.
invalid_grant: invalid assertion or a signature error	The private key in Data Integration does not match the certificate uploaded to the connected app. Re-upload the matching pair: server.key in Data Integration, server.crt in Salesforce.
invalid_client_id	The Consumer Key is incorrect. Re-copy it from Manage Consumer Details. See Save and copy the Consumer Key.
Integration user is inactive or locked	The integration user is inactive or locked in Salesforce. Reactivate or unlock the user.