This guide is for your Salesforce administrator or IT team. It takes about 30 to 60 minutes. If you have a spare standard Salesforce licence, the simpler OAuth 2.0 option in How to Connect Your Salesforce Account to zkipster may be a better fit.
Why JWT?
Salesforce includes Salesforce Integration licences with Enterprise, Unlimited and Performance editions (five licences) and Developer edition (one licence).
These users are API-only and cannot log in to the Salesforce interface. Because they cannot log in, they cannot complete the OAuth sign-in screen. JWT lets zkipster connect as this user without an interactive sign-in.
A side benefit: the connected app appears in your Salesforce as the app you create, with the name you choose, for example zkipster Integration. The name Workato connector does not appear in Salesforce on this path.
Prerequisites
• The Salesforce integration add-on is purchased and ready in zkipster. See Step 1 of How to Connect Your Salesforce Account to zkipster.
• A Salesforce Integration licence. Check under Setup > Company Information > User Licenses, and compare Used with Total for Salesforce Integration.
• A computer with OpenSSL. It is built into macOS and Linux. On Windows, you can run it from Git Bash or Windows Subsystem for Linux (WSL).
Part A: Create the integration user
1 - In Salesforce, go to Setup > Users > Users and click New User.
2 - Enter First Name zkipster and Last Name Integration, so Created By and Last Modified By in Salesforce show zkipster rather than a colleague. The username must be unique across all of Salesforce and in email format, for example zkipster.integration@yourcompany.com. The email can be a shared IT mailbox.
3 - Set User License to Salesforce Integration. The Profile list narrows to Salesforce API Only System Integrations, the only profile available for this licence. Select it.
4 - Untick Generate new password and notify user immediately. JWT does not use a password.
5 - Click Save.
6 - On the user record, under Permission Set License Assignments, click Edit Assignments and enable Salesforce API Integration.
7 - Go to Setup > Permission Sets > New. Name it zkipster Integration Access and set License to Salesforce API Integration. Under Object Settings, grant:
– Campaign: Read, to pick the Campaigns you import from and export to
– Campaign Member: Read, Create, Edit, to import members and create or update them on export
– Lead: Read, Create, Edit, to read Lead fields on import and create Leads for new Campaign Members on export
– Contact: Read, plus Edit if you export to Contacts
– Account: Read, plus Edit if you export to Accounts
Under field permissions, grant Read on every field you map on import and Edit on every field you map on export. This includes Edit on the Lead field that will store the zkipster Guest ID (see Part E). Under System Permissions, enable API Enabled.
8 - Assign the permission set to the integration user. This step is required, because object and field access cannot be set on the API-only profile.
Part B: Generate the certificate and private key
On a computer with OpenSSL, run:
openssl genrsa -out zkipster_jwt.key 2048
openssl req -new -x509 -key zkipster_jwt.key -out zkipster_jwt.crt -days 3650 -subj "/CN=zkipster-integration"
This creates two files. zkipster_jwt.crt is the certificate you upload to Salesforce. zkipster_jwt.key is the private key you paste into zkipster.
Please note: the private key is a credential. Your Salesforce admin should paste it into zkipster directly. Never send it by email, chat or Slack, and do not share it with anyone at zkipster. The certificate lasts ten years with the command above. Record its expiry date, because the connection stops working when it expires.
Part C: Create the External Client App in Salesforce
1 - Go to Setup > External Client Apps and click New External Client App. In older orgs, go to App Manager > New Connected App instead. The fields are the same.
2 - Name the app. You can choose any name; we suggest zkipster Integration. This is the name that appears in Setup > Connected Apps OAuth Usage. Enter your email as the contact.
3 - Enable OAuth. JWT does not use the callback URL, so enter https://login.salesforce.com.
4 - Under Flow Enablement, tick Enable JWT Bearer Flow and upload zkipster_jwt.crt. (If you’re using an older Connected App, tick Use digital signatures instead and upload the certificate using Choose File.)
5 - Under Selected OAuth Scopes, add Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access).
6 - Click Create, then wait 2 to 10 minutes. Connecting before Salesforce finishes setting up the app fails with a misleading error.
7 - Open the app from External Client App Manager, go to the Policies tab and click Edit. Set Permitted Users to Admin approved users are pre-authorized and IP Relaxation to Relax IP restrictions.
Using a Connected App? Go to Setup > App Manager, click the dropdown arrow next to the app, and select Manage. Click Edit Policies, then under OAuth Policies set Permitted Users to Admin approved users are pre-authorized (click OK on the confirmation pop-up) and IP Relaxation to Relax IP restrictions. Click Save.
8 - On the same screen, under App Policies, add the zkipster Integration Access permission set to Selected Permission Sets, then click Save. This is the step most often missed.
Using a Connected App? After saving the policies, you’ll be back on the app’s Manage page. Scroll down to the Permission Sets section, click Manage Permission Sets, tick zkipster Integration Access and click Save.
9 - Copy the Consumer Key from the app’s detail page.
Using a Connected App? Go to Setup > App Manager, click the dropdown arrow next to the app and select View. Under API (Enable OAuth Settings), click Manage Consumer Details. Salesforce may ask you to verify your identity with a code sent by email. Copy the Consumer Key.
Part D: Connect in zkipster
1 - In zkipster, go to Integration Hub, click the Salesforce card, then Connect.
2 - On the Setup tab, choose JWT as the authentication type.
3 - Fill in all fields:
– Issuer: the Consumer Key from Part C, step 9
– Subject: the integration user’s username. Sandbox usernames end with the sandbox name, for example zkipster.integration@yourcompany.com.uat
– Private key: the full contents of zkipster_jwt.key, including the BEGIN and END lines
– Salesforce Subdomain: if your Salesforce URL is yourInstance.salesforce.com, enter yourInstance
– Sandbox: Yes if you are connecting a sandbox, No for production
4 - Click Connect.
Part E: Choose the Lead field
1 - Open the Settings tab.
2 - Choose the Salesforce Lead field that stores the zkipster Guest ID. This is a Text field with a length of 18, which your admin creates on the Lead object. See How to Set Up the Lead Field for the Salesforce Integration.
Please note: until the Lead field is set, exports cannot create new Leads or Campaign Members. Imports, and updates to Campaign Members you imported, still work.
Part F: Check the connection
• In Salesforce, Setup > Connected Apps OAuth Usage shows your app, for example zkipster Integration, with one user.
• Run a test export that creates a new Campaign Member, open the new Lead in Salesforce, and check that Created By shows zkipster Integration.
• Check that the people in your team who need the Lead can see it. Who can see Leads created by the integration user depends on the sharing, ownership and assignment settings in your Salesforce org.
Troubleshooting
Error | Likely cause |
user hasn’t approved this consumer | Edit Policies not set to admin approved (Part C, step 7), or the permission set not added to the app (Part C, step 8) |
invalid_grant (no detail) | Wrong username (check the sandbox suffix), wrong subdomain, certificate and key do not match, app not finished setting up, or the clock is wrong on the computer that made the key |
inactive user | User not active, or licence not assigned |
Insufficient access on records | Permission set is missing object or field access (Part A, step 7) |
Worked before, now fails months or years later | Certificate has expired |