Salesforce
Purpose
Ingests one or more Salesforce orgs, with their users, profiles, roles, permission sets, groups, and connected apps. A production org and its sandboxes can sync side by side in one module.
Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.
Orgs
Add an entry under orgs for each org you want Subimage to sync. Use the org's My Domain URL, for example https://acme.my.salesforce.com for production or https://acme--dev.sandbox.my.salesforce.com for a sandbox. A Lightning URL pasted from the browser address bar (https://acme.lightning.force.com/...) works too: Subimage keeps only the host and maps it to the My Domain URL.
Each org signs in with one of:
- Default: the default credentials described below. Use this when one connected app and integration user cover the org.
- Client credentials: that org's own consumer key and client secret.
- JWT bearer: that org's own consumer key, integration username, and private key.
A sandbox is a separate org with its own users, and its usernames end in the sandbox name (subimage-integration@acme.com.dev). Give a sandbox its own credentials when its username, consumer key, or secret differs from the default ones.
An org that fails to sync does not stop the others. The sync is marked degraded and its logs name the org that failed.
Removing an org from the list stops syncing it. The data it already synced stays in the graph.
Authentication
Subimage supports two server-to-server OAuth flows. The default credentials, and each org with its own, use exactly one:
- Client credentials: the connected app has a consumer secret and a Run As user. Simplest to set up.
- JWT bearer: the connected app has an uploaded X.509 certificate and a pre-authorized integration user. Use this when your org disables the client credentials flow, or when your security policy requires certificate-based auth.
Fields
| Field | Secret? | Client credentials | JWT bearer |
|---|---|---|---|
| consumer key | No | Connected app Consumer Key | Connected app Consumer Key |
| client secret | Yes | Connected app Consumer Secret | Not used |
| username | No | Not used | Integration user's Salesforce username |
| private key | Yes | Not used | PEM private key matching the app certificate |
The sign-in method switch picks which fields apply, for the default credentials and for each org with its own. The method you are not using is cleared when you save.
Common Setup
- Create a dedicated integration user and a permission set granting API Enabled, View Setup and Configuration, and Manage Users (see Permissions for what each one unlocks). Assign the permission set to the integration user. We recommend a dedicated integration user; do not impersonate an admin.
- In App Manager, create a New External Client App (or classic Connected App) and enable OAuth. Set:
- Callback URL: any valid HTTPS URL. Neither flow uses it (e.g.
https://login.salesforce.com/services/oauth2/callback). - OAuth scope: Manage user data via APIs (api).
- Callback URL: any valid HTTPS URL. Neither flow uses it (e.g.
Then follow the steps for your flow.
Option A: Client Credentials
- In Salesforce Setup, deploy My Domain and note the URL (e.g.
https://acme.my.salesforce.com). - Enable the client credentials flow and select the integration user:
- External Client App: open Settings → OAuth Settings → Edit, enable Client Credentials Flow, then open Policies → Edit and set Run As to the integration user.
- Classic Connected App: open Manage → Edit Policies, enable Client Credentials Flow, and set Run As to the integration user.
- In Subimage, add the org's My Domain URL under orgs. Set the consumer key to the Consumer Key and the client secret to the Consumer Secret, either as the default credentials or on the org itself, then save the module.
The org URL must be its My Domain URL; login.salesforce.com does not work for the client credentials flow. If Client Credentials Flow is unavailable, deploy My Domain, then enable Allow OAuth Client Credentials Flows under OAuth and OpenID Connect Settings.
Option B: JWT Bearer
Generate a private key and a self-signed certificate:
openssl req -x509 -newkey rsa:2048 -nodes -keyout server.key -out server.crt -days 730 -subj "/CN=subimage"In the app's OAuth settings:
- Add the Perform requests at any time (refresh_token, offline_access) scope next to
api. The JWT bearer flow fails withrefresh_token scope is requiredwithout it. - External Client App: under Flow Enablement, enable JWT Bearer Flow and upload
server.crt. - Classic Connected App: enable Use digital signatures and upload
server.crt.
- Add the Perform requests at any time (refresh_token, offline_access) scope next to
Pre-authorize the integration user:
- External Client App: open Policies → Edit, set Permitted Users to Admin approved users are pre-authorized, and add the integration user's profile or permission set.
- Classic Connected App: open Manage → Edit Policies, set Permitted Users to Admin approved users are pre-authorized, then add the profile or permission set under Manage Profiles / Manage Permission Sets.
In Subimage, add the org's My Domain URL under orgs, choose JWT bearer, and set, either as the default credentials or on the org itself:
- consumer key: the Consumer Key
- username: the integration user's username (e.g.
subimage-integration@acme.com, orsubimage-integration@acme.com.devin a sandbox) - private key: the full contents of
server.key, including theBEGIN/ENDlines
Then save the module.
https://login.salesforce.com(orhttps://test.salesforce.comfor a sandbox) also works as the org URL for this flow, but only for one org each: use My Domain URLs to sync several.
Rotate the certificate before it expires (730 days in the command above) by uploading a new server.crt and updating the private key.
Permissions
Subimage only reads: it runs SOQL SELECT queries and never writes to Salesforce. Each permission on the integration user's permission set unlocks part of the org:
| Permission | What Subimage reads with it |
|---|---|
| API Enabled | The Salesforce REST API, which every query goes through. |
| View Setup and Configuration | Every profile, permission set, permission set assignment, and connected app in the org. |
| Manage Users | Each user's last password change, and the third-party apps every user has authorized (OAuthToken), not only the integration user's. |
Troubleshooting
No such column 'LastPasswordChangeDate' on entity 'User': the integration user does not have Manage Users. Add it to the integration user's permission set; the next sync picks up the org.