Configuring Salesforce Connectors

Salesforce connectors allow Stellar Cyber to ingest Salesforce logs and add them to the data lake. There can be any number of Salesforce connectors active.

Stellar Cyber connectors with the Collect function (collectors) may skip collecting some data when the ingestion volume is large, which potentially can lead to data loss. This can happen when the processing capacity of the collector is exceeded.

Connector Overview: Salesforce

Capabilities

  • Collect: Yes

  • Respond: No

  • Native Alerts Mapped: No

  • Runs on: DP

  • Interval: Configurable

Collected Data

Content Type

Index

Locating Records

Login History

Setup Audit Trail

Syslog

msg_class:

salesforce_LoginHistory

salesforce_SetupAuditTrail

msg_origin.source:

salesforce

msg_origin.vendor:

salesforce

msg_origin.category:

saas

Domain

https://<Hostname>:<Port>

where <Hostname> and <Port> are variables from the configuration of this connector

Response Actions

N/A

Third Party Native Alert Integration Details

N/A

Required Credentials

  • For Client ID / Client Secret authentication: Username, Password, Client ID, Client Secret, and Security Token

               Let us know if you find the above overview useful.

Adding a Salesforce Connector

To add a Salesforce connector in the Classic view, see Building a Connected App for API Integration and then:

  1. Add the connector in Stellar Cyber
  2. Test the connector
  3. Verify ingestion

To add a Salesforce connector in the Lightning view, see Using the Lightning View and then:

  1. Add the connector in Stellar Cyber
  2. Test the connector
  3. Verify ingestion

Building a Connected App for API Integration

You must build a connected app in Salesforce. You must use v51 (or later) of the API. As you build this app, you will need to collect the following salesforce.com information:

  • User login name and password, and the Security Token for that user

    The password should not include non-ASCII special characters.

  • Client ID (for OAuth2) or Consumer Key

  • Client Secret (for OAuth2) or Consumer Secret

  • Redirect URL (example: https://login.salesforce.com/services/oauth2/token)

The following steps are based on the salesforce.com Classic view of the console, not the Lightning view. See Using the Lightning View.

Verifying the User Requirements

This section verifies that the app's user permissions are sufficient, and that the user Security Token can be obtained. These two procedures should be completed before creating the app.

User Role

This user must have a role that includes the permission for View Setup and Configuration, so that the created app is permitted to access these needed data types:

  • SetupAuditTrail: discover new connections being configured or established

  • LoginHistory: Salesforce logins

  1. Log in as an administrative user to your salesforce.com account.

  2. Select the Setup menu option.

  3. Access the Administer > Manage Users > Users option from the left hand navigation pane.

  4. When the user list displays, locate your username, and click the Profile description at the far right.

  5. When the profile details display, locate the block for Administrative Permissions and ensure the check box for View Setup and Configuration is enabled. If it is not, then edit the profile and save the changes, or change the profile to one that has this permission enabled.

Security Token

The remaining user item is the Security Token associated with your user account. Salesforce.com does not provide a means to display this token, which is generated and emailed to you when you first created the account and password. If you do not know your token, and do not have other apps tied to this account, you can reset the Security Token with the following steps:

  1. From the top banner of the salesforce.com home page, open the menu that shows your user name, then select My Settings.

  2. The left hand navigation bar updates for your Settings. Expand the section for Personal.

  3. Select the menu option to Reset My Security Token.

  4. Since resetting the token invalidates any app using the previous token, a warning displays. To confirm that you are prepared for that result, click the Reset Security Token button. The new token is emailed to the address for the account.

  5. Make note of the Security Token for use in the Stellar Cyber connector.

Creating a Connected App

  1. Still logged in as the user above, click Setup to display the left hand navigation panel.

  2. Select the menu option for s Build > Create > Apps.

  3. The app management panel displays. Locate the section for Connected Apps and click New.

  4. Complete the fields in the Basic Information section:

    • Connected App Name: note this for use in Stellar Cyber

  5. Check the box for API (Enable OAuth Settings), then complete the following:

    • Callback URL: This is used in Stellar Cyber as the Token Endpoint URL (https://login.salesforce.com/services/oath2/token)

    • Selected OAuth Scopes: At a minimum, include Provide access to your data via the Web (in later versions, this is renamed to Manage user data via Web browsers (web)

    • Check the boxes for Require Secret for Web Server Flow and for Require Secret for Refresh Token Flow

  6. Your application view should look similar to the one depicted below. Click Save, then click Continue.

  7. The Connect App details screen displays, from where you can now collect the following information:

    • Consumer Key (or Client key for OAuth2) This is used in Stellar Cyber as the Client ID

    • Consumer Secret (or Client Secret for OAuth2) This is used in Stellar Cyber as the Client Secret

Using the Lightning View

The following steps are based on the salesforce.com Lightning view of the console, not the Classic view. See Building a Connected App for API Integration.

You will need to collect the following salesforce.com information:

  • User login name and password, and the Security Token for that user

    The password should not include non-ASCII special characters.

  • Client ID (for OAuth2) or Consumer Key

  • Client Secret (for OAuth2) or Consumer Secret

  • Redirect URL (example: https://login.salesforce.com/services/oauth2/token)

If you need to reset your Security Token, refer to the following article: https://salesforce.stackexchange.com/questions/321186/how-to-reset-security-token-of-api-only-user.

To add a Salesforce connector in the Lightning view:

  1. Add a profile
  2. Add a user
  3. Add a connected app

Adding a Profile

To add a profile:

  1. Under ADMINISTRATION, navigate to Users > Profiles and click New Profile.

  2. Select an existing profile to clone from, enter a new Profile Name, and click Save.

  3. In the new profile, under Profile Detail, click Edit.

  4. Under Connected App Access, choose an app name. See Adding a Connected App.

  5. Click Save.

Adding a User

To add a user:

  1. Under ADMINISTRATION, navigate to Users > Users, select your user, and click Edit.

  2. Choose the Profile created previously.

  3. Click Save.

Adding a Connected App

To add a connected app:

  1. Under PLATFORM TOOLS, navigate to Apps > App Manager and click New Connected App.

  2. Under Basic Information, enter a Connected App Name, an API Name, and a Contact Email.

  3. Under API (Enable OAuth Settings), choose Enable OAuth Settings and Use digital signatures. Also enter a Callback URL.

  4. Then scroll down to Selected OAuth Scopes. Use the Add and Remove arrows to move Available and Selected OAuth Scopes. Choose the following:

    • Access Lightning applications (lightning

    • Manager user data via APIs (api)

      Perform requests at any time (refresh_token, office_access).

  5. Also enable the following checkboxes:

    • Require Secret for Web Server Flow

    • Require Secret for Refresh Token

    • Enable Client Credentials Flow

  6. Scroll down and click Save. Changes can take up to 10 minutes to take effect.

  7. Click Continue.

  8. Under API (Enable OAuth Settings), for Consumer Key and Secret, click Manage Consumer Details.

  9. Click the Copy buttons to copy the Consumer Key and Consumer Secret. You need these for the Stellar Cyber connector configuration,

  10. Under PLATFORM TOOLS, navigate to Apps > Connected Apps > Manage Connected Apps and click Edit for your app.

  11. Under OAuth Policies, for Permitted Users, choose Admin approved users are pre-authorized.

  12. Scroll down and click Save.

Adding the Connector in Stellar Cyber

With the access information handy, you can add a Salesforce connector in Stellar Cyber:

  1. Log in to Stellar Cyber.

  2. Click System | Integration | Connectors. The Connector Overview appears.

  3. Click Create. The General tab of the Add Connector screen appears. The information on this tab cannot be changed after you add the connector.

    The asterisk (*) indicates a required field.

  4. Choose SaaS from the Category drop-down.

  5. Choose Salesforce from the Type drop-down.

  6. For this connector, the supported Function is Collect, which is enabled already.

  7. Enter a Name. Enter the Connected App name of the app you created.

    This field does not accept multibyte characters.

  8. Choose a Tenant Name. The Interflow records created by this connector include this tenant name.

  9. Choose the device on which to run the connector.

  10. (Optional) When the Function is Collect, you can create Log Filters. For information, see Managing Log Filters.

  11. Click Next. The Configuration tab appears.

    The asterisk (*) indicates a required field.

  12. Enter the Token Endpoint URL you copied earlier.

    For release versions prior to v4.3.4, ensure the URL does not include a trailing "/" symbol.

  13. For Client ID / Client Secret:

    1. Enter the Username of the user associated with the app you created.

    2. Enter the Password for that user.

    3. Enter the Client ID. This is the Consumer Key you copied earlier.

    4. Enter the Client Secret. This is the Consumer Secret you copied earlier.

    5. Enter the Security Token.

  14. Choose the Interval (min). This is how often the logs are collected.

  15. Choose the Content Type you would like to collect. The logs for Login History and Setup Audit Trail are supported.

  16. Click Next. The final confirmation tab appears.

  17. Click Submit.

    To pull data, a connector must be added to a Data Analyzer profile if it is running on the Data Processor.

The new connector is immediately active.

Testing the Connector

When you add (or edit) a connector, we recommend that you run a test to validate the connectivity parameters you entered. (The test validates only the authentication / connectivity; it does not validate data flow).

For connectors running on a sensor, Stellar Cyber recommends that you allow 30-60 seconds for new or modified configuration details to be propagated to the sensor before performing a test.

  1. Click System | Integrations | Connectors. The Connector Overview appears.

  2. Locate the connector that you added, or modified, or that you want to test.

  3. Click Test at the right side of that row. The test runs immediately.

    Note that you may run only one test at a time.

Stellar Cyber conducts a basic connectivity test for the connector and reports a success or failure result. A successful test indicates that you entered all of the connector information correctly.

To aid troubleshooting your connector, the dialog remains open until you explicitly close it by using the X button. If the test fails, you can select the  button from the same row to review and correct issues.

The connector status is updated every five (5) minutes. A successful test clears the connector status, but if issues persist, the status reverts to failed after a minute.

Repeat the test as needed.

ClosedDisplay sample messages...

Success !

Failure with summary of issue:

Show More example detail:

 

Verifying Ingestion

To verify ingestion:

  1. Click Investigate | Threat Hunting. The Interflow Search tab appears.
  2. Change the Indices to Syslog. The table immediately updates to show ingested Interflow records.