Skip to main content

Salesforce integration: connecting via an Integration User and Permission Set

Configuration steps in Salesforce (and Planhat) for authentication and connection

Diego Checa avatar
Written by Diego Checa
Updated over 2 weeks ago

Summary

  • We recommend that you connect to Planhat's Salesforce integration using a dedicated Salesforce "Integration User"

  • You should configure a specific Salesforce Permission Set to give the necessary access (rather than the older method of using a Salesforce Profile)

  • In this article, we also discuss Multi-Factor Authentication and Salesforce Connected Apps settings for enhanced security

Who is this article for?

  • Planhat builders (e.g. CS Ops) or Salesforce admins configuring the Salesforce integration

Series

We have a series of articles on the Salesforce integration:

Article contents

Introduction

This article guides you through how to create a suitable Salesforce Permission Set and use it to connect to the Planhat Salesforce integration.

Why a Permission Set?

Salesforce now recommends using Permission Sets rather than Profiles to manage user access. Permission Sets allow for a modular, "least-privilege" security model. Instead of cloning an entire "System Administrator" Profile to make small changes, you can simply apply a specific Permission Set to your Integration User. This method is more secure, easier to audit, and aligns with modern Salesforce best practices.

Summary of changes from older method of using a Profile

We previously recommended a setup where the required permissions were in a Profile rather than a Permission Set. Here is a quick comparison of the two approaches.

Previous method:

Profile

Current method:

Permission Set

Setup

Clone "System Admin" and strip permissions

Create a clean set with only what is needed

Maintenance

Can be hard to track which Profile does what

Easy to see exactly which permissions are granted

System access

Often granted "Modify All Data" by mistake

Restricted to specific objects + specific System Permissions

Flexibility

Rigid - one Profile per user

Stackable - add/remove permissions without changing the user's role

Setup method

Summary

  1. Create Integration User

    • MFA active via Salesforce Authenticator

  2. Create Permission Set with:

    • Specific System Permissions enabled

    • Required object and field permissions enabled

    ... and assign it to the Integration User

  3. Connect Planhat to Salesforce via an incognito window, logged in as the Integration User

  4. (Optional) "Install" Connected App in Salesforce and set to "Admin approved users"

Stage 1: Set up the Integration User

Ideally, you should connect to Planhat's Salesforce integration using a dedicated Salesforce "Integration User" (or a dedicated "dummy" user) rather than your personal Salesforce admin user account. This makes it easier to track changes in Salesforce performed by the integration (as they will show in Salesforce as being modified by that user).

  1. Create the user

  2. Verify email

    • You must verify the email address

    • 🚀 Tip: Copy the verification link sent to that email address and open it in an incognito/private browser window to avoid session conflicts with your own Salesforce login

  3. MFA Setup

    • Since this "dummy" user likely won't have an SSO (Okta/Azure) account:

      • Download the "Salesforce Authenticator" app on a mobile device

      • Log in as the new user at login.salesforce.com

      • Connect the Authenticator app to handle Multi-Factor Authentication (MFA) for this user

      • 📌 Important to note: Ensure you export/save your backup codes from the Authenticator app immediately

Can you use a "Salesforce Integration" user license?

Yes, but you will still need to assign a Permission Set to that user. The "Salesforce Integration" license is an API-only license, which is great for security, but it starts with zero access. You must follow the steps below to grant it access to objects (e.g. Account and Contact) and give it the required System Permissions.

Stage 2: Create the Permission Set and assign it to the Integration User

This Permission Set will define exactly what Planhat can access.

  1. Create new Permission Set

    • Go to "Setup" > "Permission Sets" > "New"

    • "Label": enter a clear name, e.g. Planhat Integration

    • "API Name": this will auto-populate (e.g. Planhat_Integration)

    • "License": select "None" (to ensure the set can be used by different user license types)

    • Click "Save"

  2. Enable essential System Permissions

    • In the Permission Set, go to "System Permissions" and click "Edit"

    • Enable the following permissions:

      • "API Enabled"

      • "View Setup and Configuration"

      • "View Roles and Role Hierarchy" (auto-enabled by the above)

      • "Approve Uninstalled Connected Apps" (required for the initial connection - see "Troubleshooting" below)

    • Click "Save"

    • 📌 Important to note: The reason the "View Setup and Configuration" and "View Roles and Role Hierarchy" permissions are mandatory is that the integration needs to "see" how your Salesforce org is built (the metadata) and how your teams are structured (hierarchy) to correctly fetch and map data. Without these permissions, the integration cannot see which objects or fields exist in your system, which it needs in order to show them in the mapping. We do not change your setup, but we must be able to view it

  3. Configure object settings

    • Now you must explicitly grant access to the specific Salesforce data objects you want to sync with Planhat. To do this:

      • In the Permission Set overview, click "Object Settings"

      • Click on an object you wish to sync (e.g. Account, Contact, Opportunity or Task)

      • Click "Edit"

      • "Object Permissions":

        • Select (enable) "Read" and "View All" to ensure all records are visible

        • If you also want Planhat to be able to sync data back to Salesforce via the integration, also select (enable) "Create" and "Edit"

      • "Field Permissions":

        • Ensure the specific fields you want to sync from Salesforce to Planhat (e.g. "Account Name", "Stage", etc.) have "Read Access" checked, with "Edit Access" if you want to be able to sync back to Salesforce

      • Click "Save" and repeat for the other objects to be synced

    • See below for further details

  4. Assignment

    • Click "Manage Assignments" at the top of the Permission Set page

    • Click "Add Assignment"

    • Select your dedicated Integration User

    • Click "Assign" and then "Done"

Further details on object and field permissions

The user you set up needs some access to all the objects/fields mapped in the Salesforce integration in Planhat, even if you are not syncing them, because the integration checks them all when loading.

Object permissions

Give access to:

  • Account

  • Contact

  • Note, ContentNote and ContentDocumentLink

  • Case and CaseComment

  • FeedItem (to sync comments on Chatter for Cases; now it is optional)

  • Task

  • Opportunity - or whichever object you use for subscriptions to map to the Planhat License and Sale/NRR models (noting that - at time of writing - these legacy models are soon to be deprecated and replaced by new models)

  • User

  • Profile

  • Any additional objects you have selected in the integration - e.g. OpportunityLineItem, Order, or custom objects

Field permissions

Give permissions for all fields syncing via the integration - so this is fields syncing as default and fields you've set to sync in the custom field mapping sections.

This includes:

  • Account: Name, and the field used in the filter

  • Contact: FirstName, LastName, Email, Phone, Title, AccountId, and the field used in the filter

  • Task: Subject, Description, Status, and ActivityDate (label name "Due Date")

Stage 3: Connecting Planhat (the "first handshake")

When connecting for the first time, Salesforce treats Planhat as an "Uninstalled Connected App". To make the connection:

  1. Open a new incognito/private browser window

  2. Log into Planhat with your normal credentials

  3. Navigate to the Salesforce integration (in the App Center - click "+ New app", search for and select Salesforce, and click "+ Add app" to add it to your apps list) and click "Connect"

  4. You will be redirected to a Salesforce login page

    • 📌 Important to note: If it comes up with your personal admin username, click "Not you?" or "Log in as a different user"

    • Log in using the Integration User credentials you created in Stage 1

  5. Complete the MFA challenge using the Salesforce Authenticator app

  6. Accept the OAuth prompt

Troubleshooting: "OAUTH_APPROVAL_ERROR_GENERIC"

If you see this error:

We can't authorize you because of an OAuth error... OAUTH_APPROVAL_ERROR_GENERIC : An unexpected error has occurred during authentication.

The cause: The Integration User tried to authorize a third-party app (Planhat) but lacked the permission to approve new apps.

The solution: Ensure the "Approve Uninstalled Connected Apps" permission is enabled (i.e. the box is checked) in the System Permissions of the Permission Set assigned to that user, as we described in Step 2 of Stage 2 above.

Stage 4: "Security hardening" (post-connection)

Once the connection is established, you can lock down the integration further using Salesforce's "Connected Apps" settings. This is optional, but highly recommended for security compliance.

  1. Install the app

    • In Salesforce Setup, go to "Connected Apps OAuth Usage"

    • Find the entry for "Planhat US" or "Planhat"

    • Click "Install" on the right-hand side

    • Click "Manage App Policies"

  2. Edit policies

    • Click "Edit Policies"

    • Change "Permitted Users" from "All Users may self-authorize" to "Admin approved users are pre-authorized"

    • Click "Save"

    • 📌 Important to note: By switching to "Admin approved users" you strictly control who can use the integration. Only users with the specific Permission Set can access the app, and they won't be asked to "self-authorize". (Permissions are pre-approved by you)

  3. Assign the Permission Set

    • Scroll down to the "Permission Sets" section on the Connected App detail page

    • Click "Manage Permission Sets"

    • Select the "Planhat Integration" Permission Set you created earlier (in Stage 2)

    • Click "Save"

Did this answer your question?