External Client App

Connect GRAX through Salesforce External Client Apps instead of Connected Apps

External Client Apps (ECAs) are Salesforce's newer framework for third party application integration, and they are the successor to Connected Apps. They cover the OAuth flows GRAX needs while giving administrators a more granular policy model, including per-app OAuth policies that can be managed and packaged independently.

GRAX can connect through either framework. Connected Apps remain the default and are fully supported, so there is no requirement to move to ECAs. GRAX's support for ECAs introduces a new connection technique for the Integration User that may improve connection stability.

Requirements

The second-generation Managed Package must be installed in the Salesforce org that GRAX connects to, since the GRAX External Client Apps are delivered by that package. ECA connections are not available in orgs running only the first-generation package or no package at all. If you are still on the first generation, see migrating to the second generation.

Two External Client Apps

Where a single Connected App covers both GRAX OAuth flows, the second-generation Managed Package delivers two separate External Client Apps:

• GRAX Integration, for the Integration User connection, which performs backup, restore, and archive operations. This app carries API access to your data, and GRAX authenticates through it with a signed assertion rather than by holding a refresh token.
• GRAX SSO, for end user Single Sign On into the GRAX Application. This app carries identity access only and cannot be used to reach the Salesforce data APIs.

Because they are distinct apps, each carries its own OAuth policies. IP relaxation, permitted users, and session policy can be set for the integration connection independently of the policy applied to end user logins. For example, the Integration User app can enforce IP restrictions matching your GRAX deployment while the SSO app relaxes them for a distributed user base, or SSO can be limited to admin approved profiles without affecting the integration connection.

Both flows always run through the same framework. Selecting an External Client App for the Integration User connection also moves SSO to the SSO External Client App.

Setting Up an External Client App Connection

1

Install or Update the Managed Package

Install the second-generation Managed Package into the Salesforce org that GRAX connects to, or update an existing installation to a version that includes the External Client Apps. Follow the install guide for a new installation or the update guide for an existing one.

2

Confirm the Apps Are Present

In Salesforce Setup, open "External Client App Manager" and confirm that both "GRAX Integration" and "GRAX SSO" are listed. They appear as installed, packaged apps. If they are missing, the package version installed in the org does not include them.

3

Create a Permission Set for the Integration App

The Integration app requires pre-approval for specific users via permission set, so create one in your org that will only be used for this authorization.

In Salesforce Setup, open "Permission Sets" and create a new one named for its purpose, such as "GRAX Integration App Access". It needs no object, field, or system permissions. Its only job is to name who may use the app.

Assign it to the Integration User and to no one else.

4

Set the App Policies

Open each app in "External Client App Manager" and click "Edit" for App Policies, using the tables below for the values GRAX supports. Policies are set on each app separately and they belong to your org rather than to the package, so they are preserved when the package is updated.

On the Integration app:

1. Under OAuth Policies, set Permitted Users to "Admin approved users are pre-authorized."
2. Under Select Permission Sets, choose the permission set you created. Leave Select Profiles empty.
3. Save.

The SSO app accepts either value for Permitted Users. If you set it to pre-authorization as well, authorize the relevant profiles or permission sets before anyone tries to sign in, since every user is blocked until they are authorized.

5

Connect the Integration User

In your GRAX application, select the Use External Client App instead of Connected App option, then complete the Salesforce login flow as your Integration User. The option appears in two places:

• On the initial Auto Config screen, before you connect a new GRAX Application to Salesforce.
• In Settings > Salesforce > Update, when changing or moving an existing connection.

Leave the option clear to connect through the Connected App. See Connecting Salesforce for the full connection walkthrough.

Because the app is already installed by the package, the elevated permissions a first-time Connected App install requires, such as "Approve Uninstalled Connected Apps," are not needed on the connecting user.

6

Verify

The framework in use is shown alongside the API version in the Salesforce panel of Settings, as either "Connected App" or "External Client App". Confirm it reads "External Client App," then sign in to the GRAX Application through SSO to exercise the second app.

The choice is recorded with the connection. Reconnecting keeps the framework the connection already uses unless you change the option, and switching between frameworks requires establishing a new connection.

OAuth Policy Options and Limitations

External Client App policies live under "External Client App Manager" in Salesforce Setup rather than the "Connected Apps OAuth Usage" page. Each app carries its own policies and the supported values are not the same for both, so set them separately using the tables below. As with Connected Apps, GRAX is not compatible with every possible value.

GRAX Integration App

Setting	Supported values	Impact
Permitted Users	Admin approved users are pre-authorized only	Pre-authorization is the only supported value on this app. GRAX obtains tokens for the Integration User without an interactive consent step, which Salesforce permits only for a pre-authorized user. "All users may self-authorize" leaves GRAX unable to establish or maintain the connection.
IP Relaxation	Either value	Enforcing IP restrictions requires 3.232.229.75 in the Integration User's Login IP Ranges, since GRAX authenticates from that address. If your org also enforces login IP ranges on every request, the ranges must additionally cover the addresses your GRAX application calls the API from. For a hosted or managed GRAX application, contact our Support team to arrange static IPs.
Refresh Token Policy	Any value, since it does not apply	The integration connection holds no refresh token. GRAX presents a signed assertion to Salesforce each time it needs an access token, so no refresh token is issued, stored, or exchanged.
Session policies, including the timeout	Any value, including values well below the org default	An expiring session costs one new token request, not a broken connection, since GRAX can obtain an access token at any time without user interaction.

Authorize this app with a permission set assigned to the Integration User alone, not by profile.

Profile-based authorization grants the app to every user who holds that profile, which for an integration is usually the System Administrator profile and therefore every administrator in the org. The Integration User is the only user that ever needs to be authorized here.

A permission set also guards against mistakes later. Reconnections are often performed by a different administrator, and an app authorized to a whole profile makes it easy to connect as the wrong user without anything appearing to be misconfigured. A single assignment keeps the intended user obvious and auditable.

GRAX SSO App

Setting	Supported values	Impact
Permitted Users	All users may self-authorize, or Admin approved users are pre-authorized	Self-authorization asks each user for consent the first time, which can interfere with the Lightning Web Components until the user has opened the GRAX Application once. Pre-authorization avoids the consent prompt but blocks every user, including users who authorized previously, until their profile or permission set is authorized.
IP Relaxation	Either value	GRAX authenticates end users from 3.232.229.75 as well, so enforcing IP restrictions requires that address in the Login IP Ranges of every user who signs in. Relaxing them avoids maintaining that range per user.
Refresh Token Policy	Any value, since it does not apply	Signing in requests identity only. No refresh token is issued for this app, so the policy has no effect.
Session policies, including the timeout	Any value	GRAX issues its own application session at sign in, so this policy governs the Salesforce session created during that sign in rather than how long a user stays signed in to GRAX.

The second-generation Managed Package must stay installed for as long as the connection uses the External Client Apps. Uninstalling it removes the apps and breaks the connection.

Troubleshooting

External Client App Is Not Installed in This Org

The org GRAX is connecting to has no GRAX External Client App. Confirm that the second-generation Managed Package is installed in that specific org, that its version includes the External Client Apps, and that both apps appear under "External Client App Manager".

Users Cannot Sign In After Switching

Check Permitted Users on the SSO app. If it is set to admin approved users, the relevant profiles or permission sets must be authorized on that app. If it allows self-authorization, each user consents once by opening the GRAX Application directly before using the Lightning Web Components.

The Integration Connection Cannot Authenticate

Confirm that Permitted Users on the Integration app is "Admin approved users are pre-authorized" and that the Integration User holds the permission set authorizing the app. Without pre-authorization, GRAX cannot obtain a token for that user.