Skip to Content

Salesforce JWT OAuth connection guide for Jitterbit App Builder

Note

This connection guide is the recommended process for Service Account authentication between App Builder and Salesforce. See the Security provider - Salesforce / OpenID Connect article if you are looking to configure user level Account authentication.

Prerequisites

  • You must have a Salesforce account with at least 1 active Salesforce user license and a sandbox environment to connect to.

Limitations

  • You can only have one Salesforce JWT connection per App Builder instance.

Creating a certificate

Salesforce only accepts RSA SHA256 signed JWTs, so you need an x509 Certificate and its associated private key.

  1. Download and install OpenSSL

    • OpenSSL is a full-featured tool for cryptography and secure communication. You can download it for free: https://www.openssl.org/

    • You can also install Git, as it has OpenSSL installed under the hood: https://git-scm.com/

  2. After OpenSSL is installed, proceed to create a X509 Certificate and Key

    • Open a terminal or command line, execute OpenSSL, and then run the following command to create a certificate and key file:

      req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myKey.key -out myCertificate.crt
      
    • You will be prompted to fill in details like Country, Common Name, or Email Address. You don't need to fill in all the information, but Common Name is mandatory.

    Example administrator command prompt

  3. After running the above command, you should find two files created

    Example of the files generated

Note

Be sure to note or copy the Certificate and Key files to a location that is easily accessible

Configuration in Salesforce

Now that we have our Certificate, we need to create a connected app in Salesforce.

Create a custom OAuth app

  1. Log into Salesforce.com or your Salesforce sandbox environment
  2. From the home page, go to Platform Tools > Apps > App Manager
  3. Click the New Connected App button, and enter the following:
    • Connected App Name - The name should contain the name of the system and integration, such as App Builder Integration to easily identify it, but this can be whatever you wish
    • API Name - Let Salesforce populate this based on the Connected App name
    • Contact Email - Any email you desire
    • Enable OAuth Settings - Check this checkbox, and then the following settings will appear
    • Callback URL - sfdc://oauth/jwt/success
    • Use digital signatures - Check this checkbox, then upload the myCertificate.crt file we created previously
    • Selected OAuth Scopes - Choose "Manage user data via APIs (api)", "Full access (full)", and "Perform requests at any time (refresh_token, offline_access)
  4. Click Save and then click Continue
  5. Now that the connected app is created, we need to copy down the Client ID and Client Secret for this app
  6. On the connected app's main page, click on the button titled "Manage Consumer details". This should open a new page after completing a security prompt, that contains the Client ID and Client Secret for the app. Make note of this as we will need it later.
  7. Next, we need to adjust the connected app's settings to pre-approve our user
  8. On the connected app page, click on the "Manage" button at the top of the screen, then on the next page, click the "Edit Policies" button
  9. In the OAuth Policies section, changed the Permitted Users drop down from "All users may self-authorize" to "Admin approved users are pre-authorized"
  10. Click Save
  11. Once the page refreshes, you should see a "Profiles" section near the bottom. Click the "Manage Profiles" button.
  12. Add the profile you are connecting as, in this example we are using the System Administrator profile
  13. Click Save
  14. This completes the Salesforce configuration section

Configuration on the app server

Now that we have created the app in Salesforce and uploaded our Certificate to it, we need to place the Key file on the app server that App Builder is running on, to allow App Builder to access it.

  1. On the application or App Builder server, create or use an existing folder to place the certificate and key file we generated previously. This example shows a folder created named JWT.

    JWT_folder.png

  2. Right click on the folder these files are located in, and click on Properties then the Security tab. Make sure this folder has full control to the application pool that App Builder is deployed in.

    JWT_properties.png

  3. This completes the configuration on the application server

Configuration in App Builder

Create the Salesforce ADO.NET data source in App Builder

Now that we have created the app in Salesforce and uploaded our certificate to it, we can proceed to create the Salesforce data source in App Builder.

  1. Go to the App Builder IDE and click Data Servers
  2. Click the + Server button to add a new data source
  3. Assign a Server Name
  4. Set the Type as Salesforce ADO.NET
  5. Click Save. Make sure to check the Sandbox checkbox if you are connecting to a sandbox instance.

    JWT_server.png

  6. After the data source is saved, click the Advanced Settings briefcase icon

  7. Then click Edit, and expand the Advanced section

    serveradvanced.png

  8. Configure the following settings:

    • AuthScheme - OAuthJWT
    • OAuthJWTCertType - PEMKEY_FILE
    • OAuthJWTCert -Location of the key file we created earlier, should be in a folder somewhere. For example: C:\JWT\myKey.key
    • OAuthJWTIssuer - This is the Client ID value we got from Salesforce previously.
    • OAuthJWTSubject - This should be your Salesforce email, or the email of the Salesforce user we are authenticating as.

    Note

    Input each setting in the Advanced field strung together in one line with no spaces, and separate each setting with a semicolon (;). Here is an example:

    advancedsettings.png

  9. Now that is everything is configured, scroll down and test the connection. If everything was configured correctly, you will receive a Success message.

  10. You can now import tables and access data from Salesforce