A Heroku Way of Salesforce-to-Salesforce Authentication

February 25, 2019

Developing in Salesforce CRM is tricky and requires expertise. It becomes more challenging when integration between two Salesforce orgs is required to transfer the metadata. According to the standard process, we send an authentication request to the target Salesforce org and get the access token as the response.

However, to simplify the received token in the source Salesforce org, we use Salesforce Platform Events along with the Heroku platform (a container-based cloud Platform as a Service [PaaS] that developers use to manage apps) and Lightning components (a Salesforce UI framework that is based on the concept of web components and glues the client and server together).

Seeing platform events in action

Platform events deliver secure and scalable custom notifications within Salesforce or from external sources. To customize a platform event, we define ‘Fields.’ Now, this custom platform event determines the event data that the Lightning platform can produce or consume.

There are four main steps which will produce the following results:

  • Establish a connection with the desired destination Salesforce org
  • Fetch an access token from that org and store it in the platform event

This diagram shows the overall flow of the authentication and the four steps with explanation follow it.

Fig. 1 Flow Diagram of Salesforce-to-Salesforce Authentication

Flow diagram of Salesforce-to-Salesforce Authentication


STEP 1: Create Login Window

To set the connection between two orgs in Salesforce, we need to step-in to the login page. To do that,  we add the following scripts to the respective files.

Authenticate.js - This is the script to be posted on the controller of the Lightning component where your login page resides to open the login window for authentication.


  1. loginURL - Domain URL for source org
  2. orgSuffix - Suffix provided by the user for authorization.
  3. Visualforce Page to set the URL with session Id.

Authorize.page - Session ID is necessary to complete the endpoint URL, which will be used for Heroku, as the Lightning component does not provide the session ID. For this, use the Visualforce page.

$Label.Heroku_Auth_URL - Custom Label to store Heroku Auth URL

e.g. - https:/sampleHerokuApp.com/oauth2/auth?userid=

Code Heroku Auth URL

STEP 2: Handle the Token at Heroku 

This is the key step to this integration because we need to develop three JS files on Heroku to set up a connection with JSforce and to store the access token received from the source org into the platform event.

Below is the codebase to perform the respective actions by using the following three files:

  1. Authorize.js 
  2. OAuthHelper.js  
  3. Authenticator.js 


This file sets up the connection with JSforce to authorize and callback the URL.


This is the helper class for Authorize.js file, packaged with the following methods:

  • newOAuth2: Helps in setting up the connection with JSforce.
  • notifySrcOrg:Uses the access token received from authentication and stores it in the platform event of the source org.


This file returns the fetched state tokens from the target org. Using those tokens, it fires the platform event in the source org.

Code screenshot showing fetched state tokens from the target org

Code showing Heroku Salesforce-to-Salesforce authentication

STEP 3: Set up platform events

To set up platform events in your Salesforce org, go to Home > Data > Platform Events > New Platform Event > Create New Fields.  For more details, refer to this guide to setting up Platform Events

STEP 4: Handle platform event

Finally, to utilize the efforts made for storing access tokens, handle platform events on your lightning component. Additionally, if the token has to be reused on other components or classes, handle it with Session Cache.

Reference to Handle Platform Event

Viewing the screens of authentication

After the preceding  steps are complete, the results will be as described previously:

  • A connection is established with the desired destination Salesforce org.
  • An access token fetched from that org is stored in the platform event.

The following images show what the screens of authentication with another Salesforce org will look like.

Welcome screen Salesforce.org authentication
Screen 1: Page that  initiates authentication

Pop-up box asking for Org Type and Org Prefix of the destination Salesforce org

Screen 2: Pop-up box asking for Org Type and Org Prefix of the destination Salesforce org

Screen 3: Authentication login screen for Salesforce.org

Screen 3: Authentication login screen 

Saleforce.org access confirmation page screen
Screen 4: Access confirmation page

Salesforce.org connection established with the new org screen

Screen 5: Connection established with the new org

Appirio’s Innovation in Heroku

As Heroku platform gains traction in the Salesforce world, Appirio is excited to implement automated processes for its customers’ business growth. We have a pool of innovative strategy experts who are eager to provide guidance on how your business can evolve and help you prioritize and accelerate your goals. Reach out to us to arrange a project assessment and get a customized roadmap for Salesforce Heroku implementation for your business. 


Raksha Kala is a Consultant on the Product & Innovation team at Appirio. She has a bachelor's in technology and is currently working on CASI. Raksha is a team player with a can-do attitude who is passionate about building user-focused products.

Vishal Agrawal is a Salesforce Consultant with an exceptional track record in delivering innovative IT solutions. He is on the Product Innovation team at Appirio and is currently working on CASI. Vishal is a technical expert who continuously creates amazing user experiences through development. . 


Previous Article
Simplify Sending Email to Non-Contacts with renderStoredEmail Template
Simplify Sending Email to Non-Contacts with renderStoredEmail Template

Next Article
Why B2B Social Media Should Look More like B2C in 2019
Why B2B Social Media Should Look More like B2C in 2019