Salesforce JWT OAuth Connection Guide¶

Prerequisites¶

• You must be on Vinyl version 3.1.32967 or later.
• 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 Vinyl 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.

   

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

   

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 Vinyl 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 Vinyl is running on, to allow Vinyl to access it.

1. On the application or Vinyl 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.

   

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 Vinyl is deployed in.

   

3. This completes the configuration on the application server

Configuration in Vinyl¶

Create the Salesforce ADO.NET Data Source in Vinyl¶

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 Vinyl.

1. Go to the Vinyl 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.

   

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

7. Then click Edit, and expand the Advanced section

   

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:

   

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