> For the complete documentation index, see [llms.txt](https://documentation.grax.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.grax.com/other/permissions-and-access/external-client-app.md).
# 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](/other/permissions-and-access/connected-app.md). 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](/reuse-data/managed-package/second-generation.md) 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](/reuse-data/managed-package/migrating-from-first-generation-to-second-generation-managed-package.md).
## 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](/other/permissions-and-access/integration-user.md) 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
{% stepper %}
{% step %}
### 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](/reuse-data/managed-package/second-generation/install.md) for a new installation or the [update guide](/reuse-data/managed-package/second-generation/update.md) for an existing one.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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](/other/settings/connecting-salesforce.md) 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.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% endstepper %}
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. |
{% hint style="warning" %}
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.
{% endhint %}
### 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. |
{% hint style="danger" %}
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.
{% endhint %}
## 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.grax.com/other/permissions-and-access/external-client-app.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.