Integration User

GRAX Auto Config creates the GRAX Integrations user permission set with the recommended configuration in Salesforce and assigns the permission set to the user you use to first connect the GRAX Application to your Salesforce org. This user is then used by GRAX to interact with Salesforce. We refer to this as the GRAX Integration User.

Once connected, the integration user may be reviewed or updated within the Settings tab of your GRAX app. GRAX uses this user for reading metadata and records for backup, deleting records for archives, and writing new records for restores. We require that you use dedicated Salesforce user and Permission Set for GRAX, rather than sharing a user and/or profile for GRAX and other integrations. This simplifies security, allows GRAX to automatically enforce and monitor permission problems, allows you to better audit issues, and maximizes concurrent API request limits that Salesforce imposes.

Salesforce Permissions

Required permissions are feature-specific where possible, allowing users to scope GRAX access as narrowly as possible for their use case while protecting against data loss where necessary. The table below illustrates the permissions required by each major feature. For rows marked "recommended," the GRAX product won't block usage of the feature without the related permission, but care should be taken to avoid data loss.

For compatibility with GRAX-provided scripts, these permissions must be assigned via a Permission Set named GRAX_Integration_User.

All FeaturesAPI EnabledRequiredRequired for login and API access by the integration user.
Auto Backup (Records)View All DataRecommendedEnsures that records are included in Auto Backup regardless of sharing rules.
View Encrypted DataRecommendedEnsures that encrypted fields are included in Auto Backup. Omitting this causes encrypted fields to be absent from backup data.
Auto Backup (Files)Query All FilesRequiredEnsures access to read all files for backup regardless of library and sharing rules. Omitting this may lead to a significant number of files being missed in Auto Backup.
ArchiveView All DataRecommendedEnsures Archive verification can find and match against necessary records. Omitting this may cause Archive verifications to fail.
Modify All DataRecommendedEnsures records contained within the Archive are able to be deleted. Omitting this may cause Archive executions to fail during the delete phase.
RestoreModify All DataRecommendedEnsures records can be updated and modified to match the record versions being restored. Omitting this may cause Restores to fail during record modification/creation.
Create Audit FieldsRecommendedEnsures original audit field values can be written for restore. Omitting this causes restored records to list the integration user as the source of creates or modifications to records instead of the original editor/creator.

NOTE: to grant the "Set Audit Fields upon Record Creation" permission, you must first enable it at the organization level under the "User Interface" menu within Setup. Look for the two-in-one option labeled "Enable 'Set Audit Fields upon Record Creation' and 'Update Records with Inactive Owners' User Permissions." See the Enable the 'Create Audit Fields' permission guide.

Field Level Security

Given how SFDC permission sets work, even when "View All Data" is given it's possible that GRAX is missing access to read fields on objects in a way that is transparent to the Integration User. This can lead to fields missing completely from your backups. GRAX addresses this limitation in several ways:

  1. GRAX Auto Config will automatically set all known fields to be readable by the Integration User permission set during initial setup.
  2. All users will be shown a warning banner explaining how many objects and fields are missing Field Level access when they log in to GRAX.
  3. GRAX provides an in-app tool for resolving Field Level Security issues on demand without the need to manually update each object yourself.

Recommended User Settings

These settings modify the Salesforce features that users are allowed to access. Without these, GRAX may not be able to read certain portions of Salesforce data. They can be assigned from the "User" page within Salesforce Setup.

Salesforce CRM Content UserEnsures access to read and write all Content Documents and related binary data.
Marketing UserEnsures access to read Campaign and related objects.

Mitigating Security Risks

Due to the nature of the GRAX application, it is important to understand the security risks associated with the GRAX Integration User. The GRAX Integration User is a highly privileged user that has access to all data in your Salesforce org. This user is used to read, write, and delete data in your Salesforce org. If this user is compromised, it could lead to data loss or data corruption. To mitigate this risk, we recommend the following:

  1. Enable Multi-Factor Authentication (MFA) for the GRAX Integration User.

    MFA is only required at time of login, after which GRAX will use a refresh and access token to interact with Salesforce. The Salesforce admin will need an MFA code at the time of setting up GRAX, but will not need to provide an MFA code again unless the refresh token is revoked or expires.

  2. Restrict login IP address ranges for the Integration User's profile.

    Logins and requests will only come from GRAX's HQ server, the VM running your GRAX environment, and any admins who may need to set up GRAX initially. This means only 4 static IP addresses need to be allowed to log in as the GRAX Integration User in most cases.

  3. Enforce login IP ranges on every request.

    This is a Salesforce setting that enforces the IP login ranges on every request instead of just at login. Documentation can be found here. This can prevent hijacking of a session and reuse by malicious actors.

  4. Lock sessions to the IP address from which they originated.

    This is another Salesforce setting that prevents sessions from changing IP after creation including switching between allowed IP ranges. Documentation can be found here.

  5. Enable "API Only" restrictions on the Integration User's profile.

    This prevents the user from having UI access to your Salesforce org. While this doesn't limit the user's data access, it limits the usability of the user if compromised. Documentation can be found here.

More information on secure best-practices for Integration Users can be found here.

Integration User Token Refresh

There might be the occasional need to refresh the tokens associated with the Integration User due to a sandbox refresh, expired/revoked tokens, or server configuration changes. If this is the case, you will receive an email notification and you will also see a banner notification within the GRAX application upon admin log-in. To reauthorize the Integration User, either click on the GRAX Auto Config button in the email and follow the prompts, or navigate to the Settings page in the application, expand the Salesforce section, click on Update in the blue box, and follow the prompts.

Reference Docs