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

  • For Certificate authentication: Certificate, Consumer Key, and JWT User

               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
  4. Use a Certificate for Authentication (Optional)

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.

Using a Certificate for Authentication (Optional)

Before adding the connector in Stellar Cyber, note that there are two authentication methods. The first uses Client ID / Client Secret. The second uses a certificate.

For the certificate authentication method, generate the certificate in Salesforce and upload it to the Stellar Cyber platform.

To generate the certificate in Salesforce, there are two options for the certificate and private key, self signed or public signed. The private key (.key) will be used to sign the JWT claim generated by your code. The certificate (.crt) will be uploaded to Salesforce to validate your signed JWT assertions.

The first option is a self signed certificate. Create an RSA x509 private key/certification pair, as follows, for example:

openssl req -x509 -sha256 -nodes -days 36500 -newkey rsa:2048 -keyout salesforce.key -out salesforce.crt

The second option is a public signed certificate. You can give the public CA signed certificate and private key to Stellar Cyber.

For either the self signed or public signed certificate, upload the certificate when you create the Manage Connected App. In the previous procedure, Adding a Connected App, make sure to select Use digital signatures under API (Enable OAuth Settings).

When you have the certificate, upload it to the Stellar Cyber platform on the System | Certificates page by clicking Upload. Refer to Managing Certificates for details. When you upload the certificate and private key, click Server Certificate.

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.

    • Certain connectors can be run on either a Sensor or a Data Processor. The available devices are displayed in the Run On menu. If you want to associate your collector with a sensor, you must have configured that sensor prior to configuring the connector or you will not be able to select it during initial configuration. If you select Data Processor, you will need to associate the connector with a Data Analyzer profile as a separate step. That step is not required for a sensor, which is configured with only one possible profile.

    • If the device you're connecting to is on premises, we recommend you run on the local sensor. If you're connecting to a cloud service, we recommend you run on the DP.

  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. Choose the Auth Method to use Client ID / Client Secret or Certificate.

    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.

    For Certificate:

    The asterisk (*) indicates a required field.

    1. Choose the Certificate to use from the drop-down list of uploaded certificates.

    2. Enter the Consumer Key you copied earlier.

    3. Enter the JWT User.

  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.

  18. If you are adding rather than editing a connector with the Collect function enabled and you specified for it to run on a Data Processor, a dialog box now prompts you to add the connector to the default Data Analyzer profile. Click Cancel to leave it out of the default profile or click OK to add it to the default profile.

    • This prompt only occurs during the initial create connector process when Collect is enabled.

    • Certain connectors can be run on either a Sensor or a Data Processor, and some are best run on one versus the other. In any case, when the connector is run on a Data Processor, that connector must be included in a Data Analyzer profile. If you leave it out of the default profile, you must add it to another profile. You need the Administrator Root scope to add the connector to the Data Analyzer profile. If you do not have privileges to configure Data Analyzer profiles, a dialog displays recommending you ask your administrator to add it for you.

    • The first time you add a Collect connector to a profile, it pulls data immediately and then not again until the scheduled interval has elapsed. If the connector configuration dialog did not offer an option to set a specific interval, it is run every five minutes. Exceptions to this default interval are the Proofpoint on Demand (pulls data every 1 hour) and Azure Event Hub (continuously pulls data) connectors. The intervals for each connector are listed in the Connector Types & Functions topic.

    The Connector Overview appears.

The new connector is immediately active.

Testing the Connector

The Test button for the Salesforce connector tests permissions as well as connectivity, such as if an administrator account is required.

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).

  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.