Salesforce

You can connect your Salesforce instance with InsightIDR in order to monitor your Salesforce user accounts and authentication events. This integration relies on access to the Salesforce API in order to issue API calls and receive results in InsightIDR.

However, please make sure that you meet the following Salesforce requirements and best practices:

  • You have Salesforce Enterprise Edition.
  • The URL https://login.salesforce.com is open and available for the InsightIDR Collector.
  • You have a Production instance of Salesforce. The InsightIDR Collector will not work with trial or developer instances.

It is best practice to use a dedicated read-only user with the “API Enabled” permission for this integration. This user must have at least read-only access to the User and LoginHistory objects, as well as the API Enabled permission.

Do not use a Salesforce admin user.

It is recommended that a Salesforce System Admin complete the instructions provided in this guide.

To successfully configure this event source:

  1. Configure Salesforce Permissions
  2. Create a Salesforce Token
  3. Configure Salesforce for InsightIDR

Configure Salesforce API Permissions

You must provide a user with access to the API with a setting called “API Enabled.” You can grant this permission in two different ways:

  1. User Profile Permissions
  2. Permission Set applied to the integration user

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 via their Profile:

  1. Sign in to your Salesforce instance.
  2. Navigate to Setup > Administration > Users > Users and find the user you want to use for this integration. Alternately, you can search for the integration user.
  3. Click the Profile link provided.
  1. On the “Profile” page, click the Edit button at the top of the page.
  2. Under the “Administrative Permissions” section, make sure that the API Enabled box is checked. If it is not, check the box and click the Save button.

The user now has the “API Enabled” permission from their linked Profile permissions. Any user that shares this Profile can access the API as well.

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 instance.
  2. Navigate to Setup > Administration > Users > Permission Sets.
  3. Search for an existing Permission Set or create a newPermission Set following these directions: https://help.salesforce.com/articleView?id=perm_sets_create.htm&type=5
  1. Search for “API Enabled” in the search bar, or find it under the “System Permissions” section.
  1. Make sure the “API Enabled” box is checked. If it is not, click the Edit button and check the box, and then click the Save button.
  2. At the top of the page, click the Manage Assignments button and find the designated user for this integration.
  3. Select the user’s name to assign this Permission Set.

This user can now access the API through the linked Permission Set.

Create a Salesforce Token

After the user has the proper API permissions, you must provide them with a security token.

To create a security token for this user:

  1. Sign in to Salesforce as the integration user.
  2. Expand the profile in the top right corner and select the Settings link.
  3. On the left menu, expand the My Personal Information page and select the Reset My Security Token page.
  4. Click the Reset Security Token button.
  5. The token will be emailed to the email address for the Integration user. Copy this for later use in InsightIDR.

Configure InsightIDR to collect data from the event source

In order to setup Salesforce in InsightIDR, you'll need the following information:

  • Login URL
  • Credential
  • Password
  • Security Token
  • User Account Refresh Rate (Days)
  • User Login Info Refresh Rate (Hours)

To configure the new event source in InsightIDR:

  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.com in the event sources search bar.
    • In the Product Type filter, select Cloud Service.
  3. Select the Salesforce.com event source tile.
  4. Select your collector and Salesforce.com from the event source dropdown.
  5. Name your event source.
  6. Optionally choose to send unparsed logs.
  7. Select your LDAP account attribution preference.
  8. In the "Login URL" field, provide the Login URL to your Salesforce account.
  9. Select your Salesforce credentials, or optionally create a new credential.
  10. In the "Security Token" field, provide the Security Token generated from your Salesforce account.
  11. In the "User Account Refresh Rate", enter the User Account 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.
  12. 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.
  13. Click Save.

When this event source runs successfully, you will see ingress activity and disabled account incidents.

Salesforce uses OAuth, an open source authentication standard, to integrate with other applications. For more information, read this article: https://developer.salesforce.com/docs/atlas.en-us.api_streaming.meta/api_streaming/code_sample_auth_oauth.htm.

Troubleshooting

If you are seeing the error code [LoginFault [ApiFault exceptionCode='INVALID_LOGIN' exceptionMessage='Invalid username, password, security token; or user locked out.' ] ], then you must reset the Security Token.