Access Management

Integration User

The integration user is defined within the Configuration > Setup tab. The GRAX application will use this user to log in and query metadata and data for backup and archives. It is also the user that restores data. For more general Salesforce best practices on creating integration users, see here.

We recommend the following perissions for the integration user:

PermissionComments
View All Data (or equivalent)Ensures all objects and records in the org hierarchy can be backed up
Modify All Data (or equivalent)Ensures all objects and records in the org hierarchy can be restored or archived
View Encrypted DataEnsures even encrypted values can be backed up
Query All FilesEnsures that no files get missed and cascade deleted during backups or archives
API EnabledMandatory for login
Proper Licensing for Managed PackagesSome packages requires licenses for object access
GRAX Admin Permission SetNecessary for GRAX interactions, or GRAX Support LMA
View Setup and ConfigurationFor troubleshooting by GRAX Support

Data Visibility

Always ensure the integration user has access to all data, objects, and fields that you intended to need backed up with GRAX. The integration user does the actual API queries and extraction of all information, whether it is a backup or archive.


Recommendation

We recommend using a dedicated Salesforce user specifically for GRAX rather than sharing a user for GRAX and other integrations. This will optimize security, allow you to better audit issues, and also maximize concurrent API request limits that Salesforce imposes.


Other Permissions

The table above may not be exhaustive if there are other permissions that are needed to view all data/fields. Thus, we recommend the user has profile/permissions that have been assessed to provide access to all records and fields. Note that some permissions, such as View Encrypted Data and Query All Files may not be a default even for the standard System Admin profile. You will want to understand feature-specific permissions Salesforce may require as well, such as Knowledge objects.

Configure User Access and Permissions

Any user that wants to access GRAX must first have the proper Salesforce permission set assignment(s). There are 2 supported ways to assign Salesforce permission sets.

Use Permission Sets Already Installed Via GRAX for Salesforce

The easiest way to grant a user access is to make sure they have one of the existing GRAX permission sets that comes installed as part of the Salesforce managed package, and which some users likely already have assigned to do things within the GRAX Salesforce interface.

Managed Package Salesforce Permission SetStandard User AccessPower User AccessAdmin Access
GRAX_Configuration_Admin:white-check-mark::white-check-mark::white-check-mark:
GRAX_Advanced_User:white-check-mark::white-check-mark:
GRAX_User:white-check-mark:

Create New Permission Sets

Alternatively, if you'd like to provide users access to GRAX without that meaning they’ll inherently get access to certain things in the GRAX Salesforce interface as well, you can create brand new permission sets with the exact names shown here to manage things in a more flexible manner.

These permission sets below are NOT be part of the Salesforce managed package. Instead they should be created as new permission sets in your Salesforce org, as GRAX will assume they exist with the permission set API Name specified EXACTLY per below table.

Salesforce Permission Set API NameStandard User AccessPower User AccessAdmin Access
GRAX_Console_Admin_User:white-check-mark::white-check-mark::white-check-mark:
GRAX_Console_Power_User:white-check-mark::white-check-mark:
GRAX_Console_Standard_User:white-check-mark:

GRAX Access Levels

So we've seen that you can use Salesforce permission sets to designate anyone as a GRAX Standard User, Power User, or Admin. But what specific actions can each of these user types actually perform? Let's take a closer look at the access levels:

Access LevelDashboardSearchExecutionsRestoreHistory StreamSettings
Admin UserView AllView All and Edit Search ConfigurationView All and Conduct UnarchivesView All and Conduct PITRsView All and Edit History Stream ConfigurationView All and Edit Configuration
Power UserView AllView AllView All and Conduct UnarchivesView All and Conduct PITRsView AllNo Access
Standard UserView AllView AllView AllView AllView AllNo Access

To summarize the main differences between these 3 access levels:

  • Admin User can see and do everything
  • Power User has the same access as Admin User except Power User cannot see Settings and cannot configure objects for Search or History Stream
  • Standard User also cannot see Settings and cannot configure objects for Search or History Stream. Is view only for anything else.

Access Level Indicators

You will see a callout in the GRAX navigation menu stating the current logged in user's access level.

Configure the Integration User

You will need a dedicated user that GRAX leverages to perform all functionality. We'll refer to this as the 'integration' user. This is the first thing an Admin will need to set up:

  1. Open the https://<Domain>/web/login page. You will see a prompt that asks if you want to set up a Production or Sandbox environment for OAuth. This is taking you through the OAuth flow to capture the Salesforce Integration User and store that in your customer-owned secrets manager.
  2. Use the Establish OAuth Connection to Salesforce button and log in using the Salesforce credentials of the integration user that GRAX will leverage.
  3. After this OAuth flow is successful the app will automatically reboot.
  4. After the reboot, you will see a prompt to sign in (refresh the page if you don't see this after reboot).

Permission Introspection

The dedicated integration user, in addition to all our other best practices for integration users, must have access to query the PermissionSet and PermissionSetAssignments objects.

Screen Shot 2021-11-28 at 9.38.15 AM.pngScreen Shot 2021-11-28 at 9.38.15 AM.png

You'll see a screen like this when setting up the integration user for the first time, or when you're locked out of GRAX and need to re-establish the integration user.

IP Allowlisting Considerations

If you have Salesforce IP Allowlisting (whitelisting) in place, it's very likely that GRAX will not be able to connect even after you've set up your integration user. You will need to make sure you allowlist the following 2-3 IPs:

3.232.229.75
Elastic/Static IPs of your Runtime (if you don't know this GRAX Support can help you locate)

Sign-In With Salesforce

Now that you've configured the integration user, GRAX is able to interact with the Salesforce org, and any users with the proper permission sets (per above details) can sign into GRAX.

Simply click the Sign-in with Salesforce button. You will be directed to the Salesforce sign-in page where you can enter your Salesforce credentials. GRAX will validate that this user has the proper permission set assignments and allow or deny entry to GRAX.

All other users that have the proper permission set can log in to GRAX in the same manner: open the https://<Domain>/web/login page and click Sign-in with Salesforce.

Be Careful with SSO

Be careful when you have an existing Salesforce session logged in to the browser, or especially multiple sessions. When clicking Sign-in with Salesforce, you will get logged in based on an existing session. The best practice is to ensure you are first logged out of all other browser Salesforce sessions.