> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Salesforce
> Integrate Salesforce with AirMDR using secure OAuth 2.0 authentication to enable API-based connectivity, automated workflows, alert enrichment, and controlled access to Salesforce data through Connected Apps and Remote Agent support.
## Purpose
The Salesforce integration enables AirMDR to connect with Salesforce using OAuth-based authentication and securely retrieve or act on Salesforce data through approved API access.
This guide explains how to collect the required Salesforce configuration values:
| AirMDR Field | Salesforce Value |
| :------------ | :----------------------------------------------------------------- |
| Instance URL | Salesforce org URL / My Domain URL |
| Client ID | Connected App Consumer Key |
| Client Secret | Connected App Consumer Secret |
| Remote Agent | AirMDR remote agent used to route integration traffic, if required |
Salesforce uses Connected Apps to allow external applications to integrate through OAuth and API access..
## Supported Versions
| Component | Supported Details |
| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| Salesforce | Salesforce Lightning Experience |
| Authentication | OAuth 2.0 using Connected App |
| API Access | Salesforce REST API |
| AirMDR Requirement | Valid Salesforce Instance URL, Client ID, Client Secret, and Remote Agent if the customer environment requires agent-based connectivity |
The Salesforce user configuring this integration must have permission to access **Setup**, create or manage **Connected Apps**, and view OAuth consumer details.
## Authentication
Salesforce uses OAuth 2.0 credentials generated from a **Connected App**.
| Credential | Description |
| :------------ | :--------------------------------------------------------------------------------------------------------- |
| Client ID | Salesforce **Consumer Key** generated for the Connected App |
| Client Secret | Salesforce **Consumer Secret** generated for the Connected App |
| Instance URL | Salesforce org URL, usually the My Domain URL |
| OAuth Scopes | Permissions granted to the Connected App |
| Remote Agent | AirMDR agent used when the Salesforce API endpoint must be reached through a customer-managed network path |
Salesforce requires identity verification before viewing the Consumer Key and Consumer Secret in some orgs.
### Pre-requisites
>
> Users must have Administrator access to the **Salesforce**.
>
>
>
> Dedicated Salesforce Integration User.
>
>
>
> AirMDR Remote Agent and Network Connectivity installed and active (if required by deployment model).
>
### Configure Salesforce
1. Log in to the **[Salesforce](https://login.salesforce.com/).**
2. Copy the base URL from the browser address bar.\
[https://companyname.my.salesforce.com](https://companyname.my.salesforce.com)
3. Remove any page-specific path after the domain. Use only the base URL: [https://companyname.my.salesforce.com](https://companyname.my.salesforce.com)
For sandbox environments, the URL may look similar to `https://companyname--sandbox.sandbox.my.salesforce.com`
1. Log in to [**Salesforce**](https://login.salesforce.com/) as an administrator.
2. Click the **Setup** gear icon.
3. In **Quick Find**, search for **App Manager**.
4. Select **App Manager**.
5. Click **New External Client App**.
6. Enter the basic app details:
| Field | Recommended Value |
| :----------------------- | :------------------------------ |
| External Client App Name | `AirMDR Salesforce Integration` |
| API Name | Auto-generated |
| Contact Email | Admin or SOC team email |
| Distribution State | Local |
7. Select **Enable OAuth Settings**. (Select the checkbox)
Salesforce’s Connected App configuration is used to enable OAuth settings for API integration.
In the **API (Enable OAuth Settings)** section:
1. Select **Enable OAuth Settings**.
2. Enter the Callback URL.\
**Recommended callback URL:**
```text theme={null}
https://login.salesforce.com/services/oauth2/success
```
**For sandbox:**
```text theme={null}
https://test.salesforce.com/services/oauth2/success
```
[Salesforce documentation](https://help.salesforce.com/s/articleView?id=ind.cg_task_admin_connected_apps.htm\&language=en_US\&type=5\&utm_source=chatgpt.com) lists these callback URLs as valid examples when creating a Connected App.
3. Add the required OAuth scopes. Recommended scopes:
| Scope | Purpose |
| :------------------------------------------------------------- | :------------------------------------------------------- |
| Full Access | Allows API access to Salesforce data |
| Perform requests at any time (refresh\_token, offline\_access) | Allows refresh-token based access where applicable |
| Manage User data via APIs | Required if AirMDR needs API-based user or object access |
Select only the scopes required for the approved AirMDR use case. Avoid granting broad access unless explicitly required.
4. In the **Flow Enablement**, select the check box "**Enable Client Credentials Flow**".
5. In the **Security** section, make sure "**Require secret for Web Server Flow**", and "**Require secret for Refresh Token Flow**" are selected
6. Click **Create**.
7. Click **Continue**.
Salesforce may take a few minutes to apply Connected App changes.
1. In the **External Client App Manager**, select your application "For example: AirMDR Salesforce Integration".
2. Go to **Settings** tab.
3. Select the **OAuth Settings** drop-down.
4. Under the **App settings**, you can see **Consumer Key and Secret**.
5. Copy the following values:
| Salesforce Field | AirMDR Field |
| :--------------- | :------------ |
| Consumer Key | Client ID |
| Consumer Secret | Client Secret |
Salesforce identifies the Consumer Key and Consumer Secret as the credentials used by the connected app for OAuth authentication.
1. In the **External Client App Manager**, select your application "For example: AirMDR Salesforce Integration".
2. Go to **Policies** tab.
3. Select the **OAuth Policies** drop-down.
4. In **OAuth Flows and External Client App Enhancements**
* Select the **Enable Client Credentials Flow** checkbox
* In the **Run As (Username)**, enter your Salesforce Username
5. Click **Save**.
The App Authorization Refresh Token Validity period is 365 days.
### Validate Connectivity
Use the following sample token request only for validation from an approved secure environment:
```text theme={null}
curl -X POST "https://login.salesforce.com/services/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=" \
-d "client_secret="
```
```text theme={null}
curl -X POST "https://test.salesforce.com/services/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=" \
-d "client_secret="
```
Salesforce supports OAuth 2.0 client credentials flow where the app exchanges its consumer key and consumer secret for an access token.
### Configure Salesforce in AirMDR Integrations Dashboard
1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials and click **Login**
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **Integrations**.
3. Use the search option, enter the keyword "**Salesforce**", select the **Connections** tab, and click **+ Create** button.
4. Enter an unique name to the Instance (e.g., `your org name-Salesforce`) to easily identify the user connection by AirMDR.
5. Enter the application credentials like **Instance URL, Client ID,** and **Client Secret** in the Authentication Details field params, and click **Save**.
### Skills provided by this Integration
| **Skill ID** | **Purpose** |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Create Salesforce Record | Create a new Salesforce sObject record by posting field values to `/sobjectsk/{Typer}/` |
| Get Salesforce Setup Audit Trail | Retrieve Salesforce SetupAuditTrail records with optional filters by time range, duration, user, and action. |
| Get Salesforce Event Log Files | Query Salesforce EventLogFile records and return parsed log entries. Supports filtering by event type, time range, relative duration, and log interval. |
| Delete Salesforce Record | Delete a Salesforce sObject record via `DELETE(sobjects/{Type}/{id}` |
| Get Salesforce Release Notes | Detect the connected orgs latest API version and return the canonical Salesforce release notes URL. |
| Execute Salesforce SOQL Query | Execute a SOQL SELECT statement against Salesforce and return the records (paginated automatically). Only SELECT queries are allowed. |
| Get Salesforce Report | Fetch a Salesforce Analytics report by Id. Returns reportMetadata, factMap, groupingsAcross, and groupingsDown. |
| Upsert Salesforce Record | Upsert (create or update) a Salesforce sObject record by an external Id field via `PATCH /sobjects/{Type}/{ExternalldField}/{value}` |
| Update Salesforce Record | Update an existing Salesforce sObject record via `PATCH /sobjects/{Type}/{id}` |
| List Salesforce Event Types | List the distinct EventTypes available in the Salesforce organizations EventLogFile. |
To view the details of Input Parameters and Output for the respective skills
* Go to [AirMDR → Salesforce](https://app.airmdr.com/integrationsv2/147e048d-ece3-49fe-8cc2-4ab821625235/skills?search=sales) Integration page.
* Select the **Skills** tab and click on the required listed skills.
## Additional Information
| Error | Possible Cause | Recovery |
| :----------------------- | :------------------------------------------- | :------------------------------------------------------------ |
| Invalid Client ID | Incorrect Consumer Key copied | Reopen Connected App and copy the Consumer Key again |
| Invalid Client Secret | Secret copied incorrectly or rotated | Generate or retrieve the current Consumer Secret |
| Invalid Grant | OAuth flow not enabled or policy mismatch | Review Connected App OAuth settings |
| Access Denied | User lacks required permission | Assign Connected App access through profile or permission set |
| Instance URL Unreachable | Wrong URL or network issue | Validate My Domain URL and Remote Agent connectivity |
| API Permission Error | Missing OAuth scope or Salesforce permission | Add required scope or permission to integration user |
### Salesforce Monitoring
Use the following Salesforce areas for monitoring:
| Location | Purpose |
| :--------------------------------- | :------------------------------------------ |
| Setup → Login History | Review authentication attempts |
| Setup → Connected Apps OAuth Usage | Review OAuth app usage |
| Setup → Event Monitoring | Review API and security events, if licensed |
| Setup → Debug Logs | Troubleshoot user-level execution issues |
### AirMDR Monitoring
In AirMDR:
1. Go to **Integrations**.
2. Open the **Salesforce** integration.
3. Review connection status.
4. Check recent sync or execution logs.
5. Validate any failed authentication or API request errors.
Sample log:
```text theme={null}
INFO Salesforce integration initialized
INFO OAuth token request submitted
INFO Salesforce API connection successful
ERROR Salesforce authentication failed: invalid_client_id_or_secret
```
| Environment | Recommended Level |
| :-------------- | :----------------- |
| Production | INFO / WARN |
| Troubleshooting | DEBUG temporarily |
| Security Review | Audit logs enabled |
* Use a **dedicated Salesforce integration or service account** instead of a personal user account exclusively for AirMDR integration
* Store the Salesforce **Client ID** and **Client Secret** securely using approved secret-management solutions. Never expose credentials in emails, tickets, screenshots, or shared documentation
* Enable Multi-Factor Authentication (MFA) for Salesforce administrator accounts managing Connected Apps and integration settings.
* Configure Connected App policies to allow only approved users, profiles, or permission sets to access the integration. **Monitor Authentication Activity**
* Regularly review:
* Salesforce Login History
* Connected App OAuth Usage
* AirMDR integration logs
* Failed authentication attempts
* Rotate Secrets Periodically Rotate the Salesforce Consumer Secret periodically based on organizational security policies or after any suspected credential exposure.
* Validate Remote Agent Connectivity If a Remote Agent is used, ensure it is deployed in a secure environment with controlled outbound network access to Salesforce endpoints only.
* Enforce Secure Communication Ensure all communication between AirMDR and Salesforce occurs over encrypted HTTPS/TLS connections.
* Review Integration Permissions Regularly Conduct periodic reviews of:
* OAuth scopes
* User permissions
* Connected App policies
* Remote Agent assignments
* 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) through your designated support channel.
* 🔁 Rotate credentials regularly.
* 🔄 Reconnect in AirMDR when secrets are changed.
* For integration issues, collect the following before contacting support:
```text theme={null}
Salesforce Instance URL
Connected App name
Timestamp of failed connection
AirMDR integration error message
Remote Agent name, if applicable
Salesforce login or OAuth error details
```
Do not share the Client Secret in support tickets. Share only masked values when required.