JWT Bearer Flow Guide

Owned by Harry Feasey (Unlicensed)
Last updated: Nov 12, 2019

The JSON Web Token Bearer Flow can be used to authenticate servers without interactively logging in each time the servers exchange information.

This guide will take you through creating a Connected App and installing the associated certificate into the Windows Certificate store. This will allow you to use the SFDC Explorer’s JWT Bearer Flow Login method.

Setting Up the Org and Connected App from Salesforce

 

  1. Create a Self-Signed Certificate in Salesforce to associate with your connected app.

    1. Setup > Quick Find “Certificate” > Certificate and Key Management

    2. Click “Create Self-Signed Certificate”

    3. Enter a name in the Label and Unique Name fields. Note this down for use later.

    4. Ensure “Exportable Private Key” is selected

    5. Ensure “Key Size” is 2048

    6. Click “Save” to continue to the next page.

    7. Click “Download Certificate” to get the .crt file we will use for the connected app.

  2. Create the connected app in your target org:

    1. Setup > Quick Find “Apps” > App Manager > New Connected App

    2. Enter a name and email for the app

    3. Enable OAuth Settings

    4. Enter a Callback URL (https://www.google.com will work if needed)

    5. Ensure ‘Use digital signatures’ is selected.

    6. Upload the certificate .crt file that was just downloaded.

    7. Under Available OAuth Scopes, add the following:

      1. Access and manage your data (api)

      2. Perform requests on your behalf at any time (refresh_token, offline_access)

    8. Leave everything else with the default options, click Save.

       

    9. Note that it may take up to 10 minutes for the app to work. Click Continue.

    10. Note down the “Consumer Key” value that was generated, to be used later. Pasting it into a sticky note might be a good idea.

    11. Click “Manage”

    12. Click “Edit Policies”

    13. Under OAuth Policies, set Permitted Users to “Admin approved users are pre-authorized”.

    14. Save.

    15. Now go down and click on “Manage Profiles”. Add the profiles that you want to be able to use login with the Bearer flow, and Save. For me, selecting System Administrator was enough to allow login.

  3. Export the connected app’s certificate:

    1. Setup > Quick Find “Certificate” > Certificate and Key Management

    2. Click “Export to Keystore”. Enter a password. Note this down as ‘source password’.[1]

    3. Click “Export”. A Java Key Store file will be downloaded.
      Next, we need to convert this file to a format that Windows recognises.

 

Importing the certificate to the local (Windows) key store:

 

1. Convert .jks to .pfx for install to Windows Certificate Manager:

a. Ensure you have Java Runtime Environment installed on your local machine; this contains the required ‘Keytool’ utility.

 

b. Open a new Command Prompt window with admin privilege

( Windows > Search “cmd” > Right click, “Run as Administrator” )

 

c. Change the working directory to where Java Keytool is stored, for example (with Java 8.0_191):

cd C:\Program Files\Java\jre1.8.0_191\bin

If you are in the right directory, typing keytool should display a list of available commands.

 

d. Enter the following command, with some replacements:

keytool -importkeystore -srckeystore [KEYSTORE FILE PATH].jks -destkeystore [PATH TO DESKTOP]\[NAME OF NEW FILE].pfx -srcstoretype JKS -deststoretype PKCS12 -destkeypass [NEW PASSWORD (6 characters)]

 

Things to note for this command:

- The path to desktop is not required, other locations will work as long as you have access to it. Not providing a path, however, will give an Access is Denied error.

- The new password needs to be different from the password used to lock the .jks file.

 

e. When prompted for the destination keystore password, enter the new password

f. When prompted for the source keystore, enter the password used to protect the keystore when it was created on Salesforce. (The password that was noted earlier).

g. Navigate to the destination path, and double click the created file.

2. Follow the wizard for the import process:

i. Default options are fine for the first 2 pages.

ii. Enter the new password when prompted.

iii. When asked to specify which Certificate Store should be used, choose “Place all certificates in the following store”, hit “Browse”, and select “Personal” from the list.

Using the JWT Bearer Flow login method in SFDC Explorer:

You are now set up to use JWT Bearer Flow in the SFDC Explorer.

On the JWT Bearer Flow tab, enter the following details to login:

  • Consumer key for the connected app

  • Username to login with must belong to a pre-authorized profile for the connected app

  • Name of the certificate that was used to sign the connected app.

  • Endpoint URL. Of the form “.../services/oauth2/token”

If you lose the consumer key, you can find it by searching for Apps in the Setup quick find menu and clicking View on your connected app.

 

 

[1] There is a known bug which may cause you to get an “Insufficient Privileges” error, using an empty password value can fix this – it is only a local password for installing the certificate.