Salesforce

You can connect your Salesforce account to InsightIDR to monitor your Salesforce user accounts and authentication events. This integration relies on configuring access to the Salesforce API.

The Salesforce event source polls for Salesforce users to pair future Salesforce logins with.

After this event source is configured, Salesforce login events–such as ingress activity and disabled account incidents–appear in the Ingress Authentication log set in Log Search.

There are two ways to send data from your Salesforce account to InsightIDR; event collection through the Cloud or through an on-premises Rapid7 Collector.

Cloud event sources are being phased in from December 2023

InsightIDR is adding cloud event collection capabilities to a select number of supported event sources; this one is included. This will be a phased release, so if your environment is not yet displaying the Run on Cloud option, please be patient–your environment will update shortly.

To set up the Salesforce event source, complete these steps:

  1. Read the requirements and complete the prerequisite steps.
  2. Configure Salesforce to send data to InsightIDR.
  3. Configure InsightIDR to receive data from the event source.
  4. Test the configuration.

You can also:

Requirements

Before you start the configuration:

  • Ensure that you have a license for the Salesforce Enterprise Edition.
  • You must have a production instance of Salesforce. The integration will not work with a trial or developer instance.
  • Ensure that you have Salesforce System Administrator privileges.
  • To configure this integration, you must create a dedicated read-only user that has the API Enabled permission turned on. This user must have at least read-only access to the User and LoginHistory objects.
    • This must be a non-SSO user. If SSO is enabled for this user, authentication to the Salesforce API will fail.
  • Salesforce uses OAuth, an open source authentication standard, to integrate with other applications. For more information, visit the documentation at: https://developer.salesforce.com/docs/atlas.en-us.api_streaming.meta/api_streaming/code_sample_auth_oauth.htm.

Configure Salesforce to send data to InsightIDR

To allow InsightIDR to receive data from Salesforce, you must set up a connected app in Salesforce and configure specific permissions in your Salesforce account.

To receive logs from Salesforce in InsightIDR, you must obtain these credentials:

  • Consumer ID
  • Consumer Secret
  • Username and password
  • Security Token

Complete these procedures to gather your credentials:

Configure Salesforce API Permissions

You must provide the user with access to the API with a setting called API Enabled.

You can grant this permission one of two ways:

Edit User Profile Permissions

When you assign a certain profile to a user, that user inherits the permissions of the profile.

To add the API Enabled permission to a user from their Profile:

  1. Sign in to your Salesforce account.
  2. Navigate to Setup > Administration > Users > Users and find the user you want to use for this integration. Alternatively, you can search for the integration user.
  3. Click the Profile link provided.
  4. On the Profile page, click the Edit button at the top of the page.
  5. Under the Administrative Permissions section, check the API Enabled box.
  6. Click Save.

Create a Permission Set

The second way to grant a user the necessary API permissions is to create a Permission Set and assign the Permission Set to the user. Permission Sets are additive, which means that unlike profiles, users can have zero, one, or multiple Permission Sets.

To create a Permission Set for the “API Enabled” setting:

  1. Sign in to your Salesforce account.
  2. Navigate to Setup > Administration > Users > Permission Sets.
  3. Search for an existing Permission Set or create a new one by following the instructions at: https://help.salesforce.com/articleView?id=perm_sets_create.htm&type=5
  4. Search for “API Enabled” in the search bar, or find it under the System Permissions section.
  5. Under the System Permissions section, check the API Enabled box.
  6. At the top of the page, click Manage Assignments and find the designated user for this integration.
  7. Select the user’s name to assign this Permission Set.

Create a Salesforce Token

After the user has the proper API permissions, you must configure a security token.

Reset your Salesforce security token using the instructions at: https://help.salesforce.com/s/articleView?id=sf.user_security_token.htm&type=5

Configure InsightIDR to collect data from the event source

After you complete the prerequisite steps and configure the event source to send data, you must add the event source in InsightIDR.

Task 1: Select Salesforce

  1. From the left menu, go to Data Collection and click Setup Event Source > Add Event Source.
  2. Do one of the following:
    • Search for Salesforce in the event sources search bar.
    • In the Product Type filter, select Cloud Service.
  3. Select the Salesforce.com event source tile.

Task 2: Set up your collection method

There are two methods of collecting data from Salesforce: through a cloud connection or through a collector.

New credentials are required for cloud event sources

You cannot reuse existing on-premise credentials to create a cloud connection with this event source. You must create new credentials.

Update cloud credentials after changing Salesforce password

If you change your Salesforce password or if your password expires due to the password policy of your Salesforce account, a Platform Administrator must update your cloud credentials in Insight Platform with both the new password and the newly generated token value. If the Administrator doesn't update the credentials, Salesforce events will stop being ingested some time later when the API refreshes.

Use the Cloud Connection method
  1. In the Add Event Source panel, select Run On Cloud.
  2. Name the event source. This will be the name of the log that contains the event data in Log Search. If you do not name the event source, the log name will default to Salesforce.
  3. Optionally, select the option to send unparsed data.
  4. Select your Account Attribution preference:
    • Use short name attribution: The system first attempts to attribute data by email address, for example, jsmith@myorg.example.com. If the first attempt is unsuccessful, attribution is attempted by short name, for example, jsmith. If the short name is unsuccessful, attribution is attempted by a user’s first and last name, for example, John Smith.
    • Use fully qualified domain name attribution: The system first attempts to attribute data by email address, for example, jsmith@myorg.example.com. If the first attempt is unsuccessful, attribution is attempted by a user’s first and last name, for example, John Smith. This option is best if your environment has collisions with short names.
  5. Optionally, in a multi-domain environment, use the dropdown menu to select your main Active Directory domain. See Deploy in Multi-domain Environments and Advanced Event Source Settings.
  6. Click Add a New Connection.
  7. In the Create a Cloud Connection screen, enter a name for the new connection.
  8. In the Consumer ID field, enter the Salesforce Consumer ID that you obtained in Configure Salesforce to send data to InsightIDR.
  9. In the Consumer Secret field, add a new credential:
    1. Name your credential.
    2. Describe your credential.
    3. Select the credential type.
    4. In the Consumer Secret field, enter the Salesforce Consumer Secret that you obtained in Configure Salesforce to send data to InsightIDR.
    5. Specify the product access for this credential.
  10. In the Username and Password field, add a new credential:
    1. Name your credential.
    2. Describe your credential.
    3. Select the credential type.
    4. Enter your Salesforce username.
    5. Enter your Salesforce password.
    6. Specify the product access for this credential.
  11. In the Security Token field, add a new credential:
    1. Name your credential.
    2. Describe your credential.
    3. Select the credential type.
    4. In the Security Token field, enter the Salesforce Security Token that you obtained in Configure Salesforce to send data to InsightIDR.
    5. Specify the product access for this credential.
  12. Click Save Connection.
  13. Click Save.
Use the Collector method

To setup Salesforce in InsightIDR using the Collector method, you'll need the following information:

  • Login URL
  • Credential
  • Password
  • Security Token
  • User Account Refresh Rate (Days)
  • User Login Info Refresh Rate (Hours)
  1. In the Add Event Source panel, select Run On Collector.
  2. Name the event source. This will be the name of the log that contains the event data in Log Search. If you do not name the event source, the log name will default to Salesforce.
  3. Optionally choose to send unparsed data.
  4. Select your Account Attribution preference:
    • Use short name attribution: The system first attempts to attribute data by email address, for example, jsmith@myorg.example.com. If the first attempt is unsuccessful, attribution is attempted by short name, for example, jsmith. If the short name is unsuccessful, attribution is attempted by a user’s first and last name, for example, John Smith.
    • Use fully qualified domain name attribution: The system first attempts to attribute data by email address, for example, jsmith@myorg.example.com. If the first attempt is unsuccessful, attribution is attempted by a user’s first and last name, for example, John Smith. This option is best if your environment has collisions with short names.
  5. In the Login URL field, provide the Login URL to your Salesforce account.
  6. Select your Salesforce credentials, or optionally create a new credential.
  7. In the Security Token field, provide the Security Token generated from your Salesforce account.
  8. In the User Account Refresh Rate field, enter the refresh rate in days. This field indicates how often to gather a list of Salesforce users from the application to map accounts to user identities.
  9. In the User Login Info Refresh Rate field, enter the refresh rate in hours. This field indicates how often to gather login and ingress activity related to the Salesforce users.
  10. Click Save.

Test the configuration

The event type that InsightIDR parses for this event source is Ingress Authentication.

To test that event data is flowing into InsightIDR through the Cloud Connection:

  1. View the raw logs.
    1. From the Data Collection Management page, click the Event Sources tab.
    2. Find the event source you created and click View raw log. If the Raw Logs modal displays raw log entries, logs are successfully flowing to InsightIDR.
  2. Use Log Search to find the log entries. After approximately seven minutes, you can verify that log entries are appearing in Log Search.
    1. From the left menu, go to Log Search.
    2. In the Log Search filter, search for the new event source you created.
    3. Select the log sets and the log names under each log set. Salesforce logs flow into these log sets:
      • Ingress Authentication
    4. Set the time range to Last 10 minutes and click Run.

The Results table displays all log entries that flowed into InsightIDR in the last 10 minutes. The keys and values that are displayed are helpful when you want to build a query and search your logs.

Sample logs

In Log Search, the log that is generated uses the name of your event source by default. The log appears under the Ingress Authentication log set.

To give you an impression of the event logs that this event source generates, here are some sample logs:

Sample Ingress Authentication log

 
1
{
2
"attributes": {
3
"type": "LoginHistory",
4
"url": "/services/data/v58.0/sobjects/LoginHistory/0YaHn0000EUyGdHKQV"
5
},
6
"loginTime": "2023-07-23T16:18:23.000+0000",
7
"userId": "005Hn00000H35JtIAJ",
8
"loginType": "Remote Access 2.0",
9
"loginUrl": "login.salesforce.com",
10
"sourceIp": "123.51.123.1",
11
"status": "Success",
12
"application": "New Connected App",
13
"browser": "Unknown",
14
"dataType": "User Login"
15
}

Troubleshoot common issues

Invalid credentials

If you receive this error message [LoginFault [ApiFault exceptionCode='INVALID_LOGIN' exceptionMessage='Invalid username, password, security token; or user locked out.' ] ], it means that the user has either inserted incorrect credentials or their security token has expired.

To resolve this issue, you need to reset the Security Token using the instructions at: https://help.salesforce.com/s/articleView?id=sf.user_security_token.htm&type=5.

Salesforce events are not being ingested

If you notice that Salesforce events have stopped, you may have forgotten to update your credentials (both the password and the token) after changing your Salesforce password.