Skip to main content

​
Overview

To authenticate with Salesforce using JWT, you need:
  1. Consumer Key – from your Salesforce Connected App
  2. Consumer Secret – from your Salesforce Connected App
  3. Private Key – the private key that matches the certificate you upload to the Connected App
  4. Username – the Salesforce user the JWT will act on behalf of
  5. Authorization server’s URL – the Salesforce OAuth/token endpoint base URL (see Step 6 below)
This guide walks you through generating a certificate and private key, creating a JWT-enabled Connected App in Salesforce, and entering your credentials in Nango.

​
Prerequisites

  • A Salesforce org
  • OpenSSL installed on your machine (for generating the certificate and key)

​
Instructions

​
Step 1: Create a private key and self-signed digital certificate

JWT authentication requires a digital certificate and the private key used to sign it. We recommend using your own private key and a certificate from a certification authority (CA) for production. For getting started, you can use OpenSSL to create a self-signed certificate and key. You will create two files:
  • server.key – Your private key. Use this file (or its PEM content) in Nango as Private Key.
  • server.crt – The digital certificate. Upload this file when creating the Connected App (under Use digital signatures).
Steps:
  1. Open a terminal (macOS/Linux) or Command Prompt (Windows). Check that OpenSSL is installed by running which openssl (macOS/Linux) or where openssl (Windows).
  2. Create a directory for the files and change into it, e.g. mkdir ~/JWT && cd ~/JWT.
  3. Generate a private key and save it as server.key:
    • openssl genpkey -aes-256-cbc -algorithm RSA -pass pass:SomePassword -out server.pass.key -pkeyopt rsa_keygen_bits:2048
    • openssl rsa -passin pass:SomePassword -in server.pass.key -out server.key
  4. Generate a certificate signing request: run openssl req -new -key server.key -out server.csr and enter your company information when prompted.
  5. Generate a self-signed certificate: run openssl x509 -req -sha256 -days 365 -in server.csr -signkey server.key -out server.crt.
These steps are for getting started only. For production, use a key and certificate from a CA and follow your company’s security policies.

​
Step 2: Enable creation of Connected Apps (if needed)

If your org does not allow creating Connected Apps yet:
  1. Log in to your org instance.
  2. In Setup, go to Apps → External Client Apps in the left navigation, then select Settings.
  3. Turn on Allow creation of connected apps and click Enable.

​
Step 3: Create a new Connected App

  1. From the same External Client App Settings page, click New Connected App.
  2. Fill in the basic information (e.g. app name, contact email).
  3. Select Enable OAuth Settings.
  4. For Callback URL, enter https://api.nango.dev/oauth/callback. Salesforce requires this field to be filled, but it is not used.
  5. Select Use digital signatures, click Choose File, and upload your certificate file (e.g. server.crt).
  6. Under Selected OAuth Scopes, add:
    • Manage user data via APIs (api)
    • Perform requests at any time (refresh_token, offline_access)
  7. Check the Introspect All Tokens option
  8. Click Save, then Continue.

​
Step 4: Get Consumer Key and Consumer Secret

  1. Click Manage Consumer Details.
  2. If prompted, verify your identity (e.g. enter the code sent to your email).
  3. Copy the Consumer Key and Consumer Secret; you will use these in Nango as Client ID and Client Secret.
Changes can take up to 10 minutes to take effect, please wait for these to propagate.

​
Step 5: Configure token and session policies

  1. From the left navigation go to App Manager then click the drop down to the far right of your applicaton, then click the dropdown and click manage.
  2. At the top click Edit policies, under OAuth Policies, select Admin approved users are pre-authorized, then click OK.
  1. Click Save.
  2. Click Manage Profiles (and Manage Permission Sets if needed), select the profiles or permission sets that are allowed to use this app, then click Save.

​
Step 6: Finding the authorization server URL

Use the authorization server’s URL that matches your environment:
  • Production: login.salesforce.com
  • Sandbox: test.salesforce.com
  • Experience Cloud site: site.force.com/customers (or your Experience Cloud site URL if implementing for a site)
Enter this URL in Nango as the Authorization server’s URL.

​
Step 7: Finding the username

The Username you use for JWT must belong to a user who has one of the profiles you selected in Manage Profiles above. To find a valid username:
  1. In Salesforce, go to Setup.
  2. In the Quick Find box, search for Users, then select Users.
  3. Open a user record that has one of the profiles you authorized for the Connected App.
  4. On the user detail page, copy the Username value.

​
Step 8: Enter credentials in the Connect UI

When you have your Consumer Key, Consumer Secret, Private Key, Username, and Authorization server’s URL:
  1. Open the form where you authenticate with Salesforce JWT.
  2. Enter your Consumer Key, Consumer Secret, Private Key, Username, and Authorization server’s URL in their respective fields.
  3. Submit the form, and you should be successfully authenticated.
You are now connected to Salesforce via JWT.