This article covers how to configure a Connected App for the OAuth 2.0 Client Credentials Flow and how to get an access token with the client credentials flow.

This product gathers information about a Salesforce organization’s operational events, which can be used to analyze usage trends and user behavior.

Chronicle Data Types

• SALESFORCE

Requirements

The Salesforce integration uses the OAuth 2.0 Client Credentials Flow to authenticate against the Salesforce API.

• To use the client credentials flow, you must create a connected app and configure its OAuth settings and access policies.
• Grant Admin permissions to Salesforce Connected App.
• Grant the API Enabled permissions to the connected app.
• Generate Salesforce Token
• API Hostname
• OAUTH Token Endpoint
• OAUTH Client ID
• OAUTH Client Secret
• Username
• Password

Granting API enabled permission

1. Sign into 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

4. Search for “API Enabled” in the search bar or find it under the “System Permissions” section.

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

6. At the top of the page, click the Manage Assignments button and find the designated user for this integration.

7. Select the user’s name to assign this permission set.

Configuration

Configure a Connected App for the OAuth 2.0 Client Credentials Flow

1. Getting started with the Salesforce Connected App.
   Below are the steps to create a connected app in Salesforce

• • Go to Setup->Build->Create->Apps

     

• • Click on ‘New’ in “Connected App” section.

• • Enter the Name of the Application.
  • Enter Contact Email and any additional information suitable for your application.
  • Enable OAuth settings in API section.
  • Enter a Callback URL. This is the URL that a user’s browser is redirected to after successful authentication. Here I’m giving “https://login.salesforce.com/services/oauth2/callback” as callback URL. You can enter multiple callback URLs but, you must make sure that callback URL must be secured and if multiple URLs are used, they should be separated by line breaks.
  • Add Selected OAuth Scopes. Here I’m giving “Full access(full)”.

• • Click on ‘Save’ button.
  • Click on ‘Continue’.
  • You will be redirected to your Connected App’s Page.
    

• • After creating the Connected App.
  • Click on Click to reveal link to get Consumer secret.
  • Make a note of “Consumer Key “ and “Consumer secret”, as you need these details to authenticate the external application.
  • Goto Manage->OAuth Policies-> select IP restrictions as “Relax IP restrictions”.

2. Configure the necessary OAuth settings for the connected app.

3. Enable the client credentials flow for your connected app.

• • From Setup, in the Quick Find box, enter Apps, and then select App Manager.
  • Find your connected app, click and then select Edit.
  • Under API (Enable OAuth Settings), select Enable Client Credentials Flow.
  • When you understand the security risks, accept the warning.
  • Save your changes.

4. Select an execution user for the flow.

NOTE: Permitted Users policies, such as All users may self-authorize and Admin approved users are pre-authorized, don’t apply to the execution user.

Although there’s no user interaction in the client credentials flow, Salesforce still requires you to specify an execution user. By selecting an execution user, you allow Salesforce to return access tokens on behalf of this user.

• From the connected app detail page, click Manage.
• Click Edit Policies.
• Under Client Credentials Flow, for Run As, click, and find the user that you want to assign the client credentials flow.
  The execution user must have API-only permission.
• Save your changes.

OAuth 2.0 Client Credentials Flow for Server-to-Server Integration

See Configure a Connected App for the OAuth 2.0 Client Credentials Flow.

For example, you build a custom app to run automated reports from Salesforce. You want the app to run reports every night. To integrate your custom app with Salesforce, you set up a connected app. Then, to configure your connected app for the client credentials flow, you enable the flow and assign an integration user. When the nightly report service kicks off, your custom app accesses Salesforce data using these high-level steps.

1. The connected app sends its client credentials to the Salesforce OAuth token endpoint via a POST request.
2. Salesforce validates the client credentials and authenticates the app.
3. Salesforce returns an access token on behalf of the integration user you assigned.
4. The connected app uses the access token to call a Salesforce API, such as REST API.
5. The API responds with the requested data for the report.

Note: This flow doesn’t support refresh tokens.

Request an Access Token

Let’s break down the process of getting an access token with the client credentials flow.

To initiate the flow, the connected app posts its client credentials to the Salesforce token endpoint. You can include the client credentials as parameters in the body of the request. Or, for added security, put your client credentials in a Basic Authorization header.

Here’s an example POST request with the client credentials in the request body.

POST /services/oauth2/token HTTP/1.1 Host:MyDomainName.my.salesforce.com grant_type=client_credentials& client_id=*******************& client_secret=*******************

• client_id- The consumer key of the connected app. To access the consumer key, from the App Manager, find the connected app and select View from the dropdown. Then click Manage Consumer Details. You're sometimes prompted to verify your identity before you can view the consumer key.
• client_secret- The consumer secret of the connected app. To access the consumer secret, from the App Manager, find the connected app and select View from the dropdown. Then click Manage Consumer Details. You're sometimes prompted to verify your identity before you can view the consumer secret.
• grant_type- The OAuth 2.0 grant type that the connected app requests. For the client credentials flow, this value must be set to client_credentials.

For a detailed explanation of the client credentials grant type, see Section 4.4 Client Credentials Grant in The OAuth 2.0 Authorization Framework from the Internet Engineering Task Force.

NOTE: To find your My Domain URL, from Setup, in the Quick Find box, enter My Domain, and then select My Domain.

Here’s an example of the client credentials in the Basic Authorization header. With this format, the client_id is appended to the client_secret in the format client_id:client_secret, and the resulting value is Base64-encoded.

POST /services/oauth2/token HTTP/1.1 Host: MyDomainName.my.salesforce.com Header: Authorization: Basic TXlDbGllbnRJRDpNeUNsaWVudFNlY3JldA== grant_type=client_credentials

If you use this format, the grant_type is the only required parameter in the request body. The grant_type must be set to client_credentials.

NOTE: Because Salesforce doesn’t support scopes on the token endpoint, you can’t include scopes in the request. Instead, assign scopes to your connected app.

Salesforce Grants an Access Token

After validating the client credentials, Salesforce returns a response containing an access token and the requested scopes. The app can use the access token to access protected data in Salesforce.

Here’s an example access token response in JSON format.

{     "access_token": "*******************",     "instance_url": "https://yourInstance.salesforce.com",     "id": "https://login.salesforce.com/id/XXXXXXXXXXXXXXXXXX/XXXXXXXXXXXXXXXXXX",     "token_type": "Bearer",     "scope": "id api",     "issued_at": "1657741493799",     "signature": "c2lnbmF0dXJl" }

• access_token- OAuth token that a connected app uses to request access to a protected resource on behalf of the client application. Additional permissions in the form of scopes can accompany the access token.
• instance_url- A URL indicating the instance of the user’s org.
  For example: https://yourInstance.salesforce.com/.
• token_type- A Bearer token type, which is used for all responses that include an access token.
• Scope- The scopes associated with the access token.

Scopes further define the type of protected resources that the client can access. You assign scopes to a connected app when you build it, and they’re included with the OAuth tokens during the authorization flow.

Because the client credentials flow doesn’t support UI sessions and doesn’t issue a refresh token, Salesforce automatically filters out these scopes.

• Full access (full)
• Manage user data via Web browsers (web)
• Perform requests at any time(refresh_token, offline_access)

issued_at- Time stamp of when the signature was created in milliseconds.

Signature- Base64-encoded HMAC-SHA256 signature signed with the client_secret. The signature can include the concatenated ID and issued_at value, which you can use to verify that the identity URL hasn’t changed since the server sent it.

Configure a feed in Chronicle 

Complete the following steps to configure a feed in Chronicle to ingest the Salesforce logs:

1. Go to Chronicle settings and click Feeds.
2. Click Add New.

3. Select Third Party API for Source Type.

4. Select Salesforce for Log Type.

5. Click Next.

6. Under the required field, paste the data collected by the above process.

7. Click Next and Finish.