> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/open-telemetry/configuration/salesforce-setup.md).

# Salesforce Setup

Create the External Client App and RSA keypair Hermes authenticates with, assign a read-only running user, and set per-org export behavior in Salesforce.

Everything Hermes needs from Salesforce is set up once per org: an authentication mechanism, a running user with read-only access, and a per-org settings record. This page walks through all three. Complete it before deploying to [AWS](https://docs.pharos.ai/open-telemetry/configuration/aws.md) or [Azure](https://docs.pharos.ai/open-telemetry/configuration/azure.md) — the cloud Terraform modules assume these Salesforce-side pieces already exist.

***

## Prerequisites

* **Admin access** to the target Salesforce org — you'll need to create an External Client App (or Connected App) and a metadata record.
* [**Pharos Triton**](https://triton.pharos.ai/installing-pharos-triton) **2.0 or later installed**, if this org will use **Iris** (application telemetry). Argus (Event Monitoring) needs no Triton instrumentation.
* **The ability to generate an RSA keypair** on whatever machine you use for setup — you'll upload only the public key/certificate to Salesforce; the private key stays with you and gets placed in your cloud's secrets vault later.

***

## Setup Steps

{% stepper %}
{% step %}

### 1. Create an External Client App (or Connected App)

In Salesforce Setup, create a new **External Client App** (or, on orgs that still use them, a **Connected App**) dedicated to Hermes. This is the identity Hermes authenticates as when it opens its Pub/Sub API gRPC stream.
{% endstep %}

{% step %}

### 2. Generate an RSA keypair and upload the public key

Generate an RSA keypair outside Salesforce, for example:

```bash
openssl genrsa -out hermes.private.key 2048
openssl req -new -x509 -key hermes.private.key -out hermes.certificate.crt -days 730 \
  -subj "/C=US/ST=CA/O=YourOrg/CN=hermes"
```

Upload the **certificate** to the External Client App under **Certificates** to enable the **JWT Bearer OAuth flow**. Keep the **private key** — Hermes needs it (as `sf.private_key` in `ORG_CONFIGS`, stored in your cloud's secrets vault) to sign JWT assertions at runtime.
{% endstep %}

{% step %}

### 3. Configure OAuth scopes — and disable JWT-based access tokens

Enable OAuth settings for the app and configure its OAuth scopes: `Api`, `RefreshToken`, `OfflineAccess`, `SFApiPlatform`. Then check the **"Issue JWT-based access tokens"** setting and make sure it is **disabled**.

{% hint style="info" %}
These four scopes (`Api`, `RefreshToken`, `OfflineAccess`, `SFApiPlatform`) are what's configured on the External Client App itself. Separately, once the JWT Bearer flow succeeds, the access token response's `scope` string must include `api` and `sfap_api` — that's the value the Pub/Sub API actually checks at request time, and it's what the warning below refers to.
{% endhint %}
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Critical: "Issue JWT-based access tokens" must be DISABLED.** If this setting is enabled, Salesforce's JWT Bearer flow returns a self-contained `eyJ…`‑style access token — and the Pub/Sub gRPC API **rejects it**. The Pub/Sub API needs a classic Salesforce session token in the `00D…!…` format, which is only issued when this setting is left off, and only when the app's OAuth scopes include both `api` and `sfap_api`. This is the single most common cause of Hermes failing to authenticate on first setup.
{% endhint %}

{% stepper %}
{% step %}

### 4. Note the consumer key

Once the app is saved, note its **consumer key** (client ID) from the app's settings page. This is one of the values Hermes needs in `ORG_CONFIGS` (`sf.client_id`) — you'll store it, alongside the private key, in your cloud's secrets vault during deployment.
{% endstep %}

{% step %}

### 5. Create a dedicated, read-only running user

Create (or designate) an integration user for Hermes to run as, and grant it **read-only** access — nothing more. See **Running User & Permissions** below for exactly what it needs.
{% endstep %}

{% step %}

### 6. Configure `OTel_Configuration__mdt`

Create or edit the `OTel_Configuration__mdt` custom metadata record for this org, and set `Export_Mode__c` to the value that matches how you want Iris to behave. See **`OTel_Configuration__mdt`** below for the field reference.
{% endstep %}
{% endstepper %}

***

## Running User & Permissions

The Salesforce user Hermes authenticates as should have **read-only** access to the telemetry and identity data it needs, and nothing else. Pharos packages that access as two permission sets, one per component — assign them to the running user rather than piecing the access together by hand. Both ship in the [pharos-permissions](https://resources.pharos.ai/pharos-permissions) download: deploy it to your org, then assign the sets that match the components this org runs.

**`Hermes_Iris`** (label "Hermes Iris") — everything Iris needs to subscribe to the `pharos__Log_Event__e` platform event, and nothing more:

* `API Enabled`
* `View All Platform Events`

**`Hermes_Argus`** (label "Hermes Argus") — everything Argus needs for Event Monitoring ingestion:

* `API Enabled` and `View All Platform Events` — the RTEM platform-event subscription.
* `View Event Log Files` and `Event Log Read Access` — querying `EventLogFile` records and downloading the log files themselves, for Argus ELF.
* `View Threat Detection Events`, as `ViewAnomalyEvents` and `ViewDataLeakageEvents` — the Threat Detection RTEM channels.
* `View All Data`, plus the permissions it depends on — `View Public Dashboards`, `View Public Reports`, `View Roles and Role Hierarchy`, `View Setup and Configuration` — which is what backs Argus's read access to `AuthSession` for cross-channel session unification.

The first two permissions appear in both sets on purpose, so each set is independently sufficient for its own component. Hermes never writes back into your org — there's no product logic running inside Salesforce, and no write permission the running user needs to grant.

{% hint style="warning" %}
**If this org runs both components, assign both permission sets.** With only `Hermes_Iris` assigned while Argus is running, session resolution degrades silently — Iris keeps the session context the Apex trigger supplied, Argus resolves its own, and the two components' telemetry stops grouping into one trace. Nothing errors and no telemetry is lost, so the only symptom is traces that should have been joined arriving separately.
{% endhint %}

{% hint style="info" %}
An **Iris-only** org needs `Hermes_Iris` alone, and therefore does not need `View All Data` at all — Iris gets the session from the log payload. Only Argus reads `AuthSession`, because Event Monitoring events carry no session context of their own. If your security policy bars `View All Data`, `Hermes_Argus` can use **`Manage Users`** instead, which grants the same `AuthSession` read over far less data — but `Manage Users` is write-capable, so it trades read breadth for write access rather than being a strict reduction.
{% endhint %}

***

## `OTel_Configuration__mdt`

This custom metadata type holds per-org Hermes settings. The field that matters most is `Export_Mode__c`, which controls how Iris exports telemetry for this org:

| Field            | Values                       | Purpose          |
| ---------------- | ---------------------------- | ---------------- |
| `Export_Mode__c` | `Off` / `LWC_Go` / `Go_Only` | See table below. |

| `Export_Mode__c` value | Behavior                                                                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Off`                  | Hermes/Iris OTel export is disabled for this org.                                                                                                        |
| `LWC_Go`               | Both paths run: LWC telemetry uses the client-side direct-push path; Apex, Flow, and Integration telemetry flows through the Go (Iris) Pub/Sub pipeline. |
| `Go_Only`              | All telemetry, including LWC, flows through the Go (Iris) Pub/Sub pipeline; the LWC direct-push path is not used.                                        |

The record also carries other per-org identification and labeling settings alongside `Export_Mode__c` — check the record's field list in Setup for the exact set on your package version. The OTLP endpoint and credentials for your backend are **not** stored here; those live in your cloud's secrets vault, configured as part of [`ORG_CONFIGS`](https://docs.pharos.ai/open-telemetry/configuration/org-configs.md).

{% hint style="info" %}
`Export_Mode__c` only controls Iris (application telemetry). Argus (Event Monitoring — RTEM and ELF) is unaffected by this setting; it's enabled independently through `ORG_CONFIGS`.
{% endhint %}

***

## Considerations

* **Multi-org.** A single Hermes deployment can serve multiple Salesforce orgs (1–20) in one process. Repeat this Salesforce-side setup — External Client App, running user, `OTel_Configuration__mdt` record — for each org you want Hermes to cover.
* **Authentication modes.** `ORG_CONFIGS` carries JWT Bearer credentials only, and that is the mode every cloud deployment uses. Hermes also accepts a username-password grant (`SF_PASSWORD`) or a static access token (`SF_ACCESS_TOKEN` + `SF_INSTANCE_URL`) from environment variables for single-org local runs; both are ignored whenever `ORG_CONFIGS` is set. See [Security](https://docs.pharos.ai/open-telemetry/hermes/security.md#authentication).
* **Pre-authorization policy.** The External Client App uses an admin-approved pre-authorization policy; by default, it pre-authorizes only the **System Administrator** profile, which is why the running user has historically needed to be an admin. To run Hermes as a scoped, non-admin integration user instead, pre-authorize a permission set that user is assigned — `Hermes_Iris`, `Hermes_Argus`, or both, matching the components this org runs — on the app, or keep the running user on a profile the app already pre-authorizes. Assignment and pre-authorization are separate steps: assigning a set grants the permissions, while pre-authorization is what admits the user to the app.
* **Login IP ranges.** If the app enforces IP restrictions, add the runtime's egress IP addresses to Login IP Ranges or Trusted IPs — otherwise JWT logins from your cloud environment can trigger identity verification and fail non-interactively.
* **Rotating the keypair.** If you rotate the RSA keypair, upload the new certificate to the External Client App and update the private key in your cloud's secrets vault at the same time — a mismatch between the two breaks authentication until they're back in sync.
* **Troubleshooting auth failures.** If Hermes can't authenticate after setup, the JWT gotcha above is the first thing to check, followed by the running user's permissions and the `api`/`sfap_api` scopes on the app. The `hermes_org_auth_failures_total` [self-metric](https://docs.pharos.ai/open-telemetry/configuration/self-metrics.md) counts every rejection.

***

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🟠 AWS Deployment</strong></td><td>ECS Fargate, DynamoDB, staged Terraform</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/aws.md">AWS Deployment</a></td></tr><tr><td><strong>🔵 Azure Deployment</strong></td><td>Container Apps, Table Storage, staged Terraform</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/azure.md">Azure Deployment</a></td></tr><tr><td><strong>🧩 ORG_CONFIGS Reference</strong></td><td>Where the consumer key and private key are actually configured</td><td><a href="https://docs.pharos.ai/open-telemetry/configuration/org-configs.md">ORG_CONFIGS Reference</a></td></tr><tr><td><strong>🌈 Iris</strong></td><td>How Export_Mode__c shapes the Iris pipeline</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/iris.md">Iris</a></td></tr><tr><td><strong>🔐 Security</strong></td><td>Full authentication and permissions posture</td><td><a href="https://docs.pharos.ai/open-telemetry/hermes/security.md">Security</a></td></tr></tbody></table>
