OAuth JWT Login

How to Login to Salesforce as an External Client App

This page provides instructions for connecting to Salesforce using certificate-based / JWT authentication.

To connect to Salesforce using JWT authentication it is necessary configure an External Client App with a certificate, and to provide the certificate and OAUTH Client Id to CapStorm.

Step 1: Create a Certificate

Create a certificate using CapStorm by selecting the JWT credential type and exporting the certificate file.

To select the JWT credential type:

1. Click on the Edit button for Advanced Parameters.

2. Select Oauth 2.0 JWT in the dropdown.

To Save the certificate:

This will create two files:

1. The certificate and private key are stored in a file CapStorm_JWT.jks in the CapstormConfig folder.

   1. The CapstormConfig folder is a folder next to the application folder.

   2. For example, if CopyStorm is installed in C:\CapStorm\CopyStorm

   3. Then the CapstormConfig folder will be C:\CapStorm\CapstormConfig

2. The exported PEM file.

Step 2: Create an External Client App

Create an External Client App using the PEM file exported in Step 1.

Login to Salesforce and go to Setup. Search for External Client App Manager in the Quick Find box, and click on New External Client App.

Enter app details:

1. External Client App Name

2. API Name

3. Contact Email

4. Callback URL

   1. NOTE: This field is required, but the value for Callback URL is not used for JWT Apps.

   2. Enter https://localhost/ as the Callback URL.

5. OAuth Scopes

   1. At a minimum, the following scopes must be selected:

      1. Access the identity URL service (id, profile, email, address, phone).

      2. Manage user data via APIs (api).

      3. Perform requests at any time (refresh_token, offline_access).

6. Enable OAuth

   1. This checkbox must be checked.

7. Enable JWT Bearer Flow

   1. This checkbox allows JWT access.

8. Certificate Upload

   1. Upload the PEM file that was saved in Step 1.

9. Click on “Create” to create the External Client App.

Then, click on “Create”.

After creating the External Client App, configure app policies to allow access.

Click on “Edit” for App Policies, and update the policy to enable appropriate users. In this example, a Permission Set is used to grant access to the app:

1. Under OAuth Policies, change Permitted Users to:

   1. Admin approved users are pre-authorized.

2. Under Select Profiles and Select Permission Sets:

   1. Select the Permission Set(s) or Profile(s) that should be granted access to the External Client App.

   2. CapStorm recommends configuring a Permission Set to limit App access.

3. Click on “Save” to save the App policies.

Step 3: Configure CapStorm

To configure CapStorm, the Oauth Client Id (Consumer key) from the External Client App will be needed.

1. Go to the Settings tab of the External Client App.

2. Under OAuth Settings, click on Consumer Key and Secret.

3. In the Consumer Details page, copy the Consumer Key.

Copy the Consumer Key:

Now, to finish configuring CapStorm:

1. Copy the Consumer Key value into the OAuth Client Id text box.

2. Enter the Salesforce User’s username into the Username text box.

   1. The user must be a member of the Permission Set or Profile configured in the OAuth policy.

3. Enter the Salesforce instance’s host name into the Salesforce Host text box.

   1. Sandboxes will have host names like:

      1. mycompany–mysandboxname.sandbox.my.salesforce.com

   2. Production orgs will have host names like:

      1. mycompany.my.salesforce.com

4. Click on Test Connection to verify.

To verify the connection, click on the “Test Salesforce Connection” button. If successful, the below window will appear:

Custom Certificate

The custom certificate checkbox allows users to create and use their own custom java keystore file, separate from the built-in Java JRE keystore. By enabling this checkbox, several new fields will appear in the login form:

The process of configuring OAuth JWT login with a custom certificate is largely similar to the above steps, the main differences being:

• OAuth Public and Private keys will need to be generated manually

• The Certificate will need to be generated manually from the public and private keys

• The certificate will need to be added to a java keystore file or a PKCS12 file

• Keystore info (file path, keystore password, key password, and name) must be entered manually into CopyStorm

After manually generating the above keys and files, the rest of the setup is largely similar to the non-custom certificate flow. Create an external client app, upload the certificate to the external client app, configure the external client app, and finally configure CopyStorm.

For more information on generating keys and certificates for use in Salesforce OAuth JWT, see this Salesforce Documentation.

OAuth Custom Certificate Connection Parameters

Parameter Name	Default Setting	Required	Description
Keystore		Yes	Path to a JKS or PKCS12 Keystore containing the private key used to sign JWT requests.
Keystore Password		Yes	Password used to access the Keystore (blank if the Keystore does not have a password).
Key Name		Yes	The name of the private key used to sign JWT requests.
Key Password		Yes	The password used to access the private key.
OAUTH Client Id		Yes	The Salesforce-generated Client Id for the Connected Application.
Username		Yes	The login Id of the CopyStorm Salesforce user.
Custom Certificate	Unchecked	No	Check this box to use a custom-made Java keystore file (.jks). Leaving the box unchecked will cause the application to use the default Java key store.
Token Validity (minutes)	240	Yes	The lifetime of JWT access tokens. If the token expires during the CopyStorm run, CopyStorm will re-authenticate and get a new token.