Documentation Plugins Salesforce data source Configure the Salesforce data source

Configure the Salesforce data source

This document explains configuration options for Salesforce data source in Grafana.

Before you begin

Before you can configure the Salesforce data source, ensure you have the following:

• The Salesforce data source plugin installed. For installation instructions, refer to Install Grafana Enterprise plugins.
• A Salesforce account.
• A Salesforce app configured with OAuth settings. Choose one of the following:
  • New setups (recommended): An External Client App with JWT authentication (refer to External Client App settings).
  • Existing setups: A Connected App configured with OAuth settings (refer to Connected App settings).
• Any free or paid Grafana Cloud plan or an activated Grafana Enterprise license.
• Grafana version 9.5.13 or later.
• The Organization Administrator role in Grafana to add data sources.

Salesforce app configuration

Grafana supports two authentication methods with the Salesforce data source: Credentials or JWT.

Before configuring the Salesforce data source, you must set up an app in Salesforce to enable OAuth authentication. Salesforce offers two app types: External Client Apps (ECAs) and Connected Apps.

External Client App settings

External Client Apps (ECAs) are Salesforce’s recommended approach for new integrations. ECAs support JWT-based authentication, which is the recommended authentication method for the Grafana Salesforce data source.

To create an External Client App for JWT authentication:

1. In Salesforce Setup, search for App Manager and select it.
2. Click New External Client App.
3. Enter a name and contact email for your app.
4. Under OAuth Settings, configure the following:
   • Enable OAuth Settings: Select this option.
   • Callback URL: Enter sfdc://oauth/jwt/success.
   • Use Digital Signatures: Select this option and upload your public certificate file (.crt). To generate a certificate, refer to Generate a Self-Signed Certificate.
   • Selected OAuth Scopes: Add the following scopes:
     • Access and manage your data (api)
     • Perform requests on your behalf at any time (refresh_token, offline_access)
5. Save the app.
6. After saving, navigate to the app’s OAuth Settings to obtain the Consumer Key.

Configure user access for JWT

After creating the External Client App, configure user access:

1. In Salesforce Setup, search for Permission Sets and create a new permission set for JWT access.
2. In the permission set, click Assigned Connected Apps and add your External Client App.
3. Assign the permission set to the Salesforce user that Grafana will use for authentication.
4. In App Manager, find your app and click Manage.
5. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized.

For more information, refer to Salesforce’s Configure OAuth JWT Flow for External Client Apps.

Connected App settings

If you have an existing Connected App or have requested the ability to create one from Salesforce Support, configure the following settings.

Credentials-based Connected App settings

If you are using the Credentials authentication method with an existing Connected App, you must set the following:

• Enable OAuth settings: Select this option to enable OAuth.
• Callback URL: Required in Salesforce but not used by the Grafana Salesforce plugin. You can use any valid URL.
• Selected OAuth Scopes (minimum requirements): Select the following scope:
  • Access and manage your data (api)
• Require Secret for Refresh Token Flow: Can be enabled or disabled.

JWT-based Connected App settings

If you use JWT authentication with an existing Connected App, you must set the following:

• Enable OAuth settings: Select this option to enable OAuth.
• Callback URL: Enter sfdc://oauth/jwt/success.
• Use digital signatures: Select this option and upload the digital certificate.
• Selected OAuth Scopes (minimum requirements): Select the following scopes:
  • Access and manage your data (api)
  • Perform requests on your behalf at any time (refresh_token, offline_access)
• Require Secret for Refresh Token Flow: Can be enabled or disabled.

For new setups, refer to External Client App settings for the recommended approach using External Client Apps.

Add the Salesforce data source

For general information on installing and managing plugins and data sources in Grafana refer to the following documents:

• Install Grafana plugins
• Plugin management
• Data source management

To install the Salesforce data source plugin, refer to Grafana’s Salesforce installation page.

Once you have installed the Salesforce plugin, complete the following steps to add the Salesforce data source:

1. Click Connections in the left-side menu.
2. Enter Salesforce in the search bar.
3. Select the Salesforce data source tile.
4. Click Add new data source in the upper right.
5. You are taken to the Settings tab where you will set up your Salesforce configuration.

Salesforce configuration options

Following is a list of configuration options for Salesforce.

The first option is to give the connection a name:

• Name - The name for your data source. This is how you refer to the data source in queries and panels. Examples: Salesforce_Sales_Prod1, SF-Prod-East1.
• Default - Toggle to select the default name in dashboard panels. This will set it as the default data source when you access a dashboard panel.

Connection settings

Grafana supports two authentication methods with the Salesforce data source: Credentials or JWT.

Credentials-based authentication

Following are configuration options for Credentials-based authentication:

• User name: The user name for the Salesforce account used to connect to Salesforce. Examples: salesforce_admin@abccompany.com.
• Password: The password used to connect to Salesforce.
• Security token: Add the security token.
• Consumer key: The consumer key used to connect to Salesforce. You obtain this from your Connected App.
• Consumer secret: The consumer secret used to connect to Salesforce. You obtain this from your Connected App.

JWT-based authentication

JWT-based authentication is the recommended method for new setups and works with both External Client Apps and Connected Apps.

• For External Client Apps, refer to External Client App settings.
• For Connected Apps, refer to Salesforce’s Configure a Connected App to Issue JWT-Based Access Tokens.

Add the following under Digital Signature:

• Certificate: The certificate that is used as the digital signature in your Salesforce app. To generate a certificate, refer to Generate a Certificate Signed by a Certificate Authority. To generate a self-signed certificate, refer to Generate a Self-Signed Certificate.
• Private key: Add the private key for the certificate.

Add the following under App Credentials:

• User name: The user name for the Salesforce account used to connect to Salesforce. Examples: salesforce_admin@abccompany.com.
• Consumer key: The consumer key used to connect to Salesforce. You obtain this from your External Client App or Connected App.

Optional settings

• Environment - Click the drop-down to select your environment.

• Private data source connect - Only for Grafana Cloud users. Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC refer to Private data source connect (PDC).

Once you have added your connection settings, click Test to test the data source connection.

Configure the data source with provisioning

Configure the Salesforce data source using Grafana’s provisioning system by defining settings in YAML files. For details on the provisioning system and configuration options, refer to Provisioning Grafana.

The following example is for provisioning the Salesforce data source:

YAML Copy

apiVersion: 1
datasources:
  - name: Salesforce - user password authentication
    type: grafana-salesforce-datasource
    jsonData:
      authType: user
      user: user name
    secureJsonData:
      password: password
      securityToken: securityToken
      clientID: consumer key
      clientSecret: consumer secret
  - name: Salesforce - jwt authentication
    type: grafana-salesforce-datasource
    jsonData:
      authType: jwt
      user: user name
    secureJsonData:
      clientID: consumer key
      cert: |
        -----BEGIN CERTIFICATE-----
        xxxxxxxxxxxxxxxxxxxxxxxxxxx
        -----END CERTIFICATE-----
      privateKey: |
        -----BEGIN PRIVATE KEY-----
        xxxxxxxxxxxxxxxxxxxxxxxxxxx
        -----END PRIVATE KEY-----

To provision a sandbox environment, update the jsonData setting with the sandbox property:

YAML Copy

jsonData:
  sandbox: true

Configure the data source with Terraform

You can configure the Salesforce data source as code using the Grafana Terraform provider. This approach enables version-controlled, reproducible data source configurations across environments.

The following examples demonstrate configurations for Credentials-based and JWT-based authentication.

Credentials-based authentication

terraform Copy

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = "~> 3.0"
    }
  }
}

provider "grafana" {
  url  = var.grafana_url
  auth = var.grafana_auth
}

resource "grafana_data_source" "salesforce_credentials" {
  type = "grafana-salesforce-datasource"
  name = "Salesforce"

  json_data_encoded = jsonencode({
    authType = "user"
    user     = var.salesforce_username
  })

  secure_json_data_encoded = jsonencode({
    password      = var.salesforce_password
    securityToken = var.salesforce_security_token
    clientID      = var.salesforce_consumer_key
    clientSecret  = var.salesforce_consumer_secret
  })
}

JWT-based authentication

terraform Copy

resource "grafana_data_source" "salesforce_jwt" {
  type = "grafana-salesforce-datasource"
  name = "Salesforce JWT"

  json_data_encoded = jsonencode({
    authType = "jwt"
    user     = var.salesforce_username
  })

  secure_json_data_encoded = jsonencode({
    clientID   = var.salesforce_consumer_key
    cert       = var.salesforce_certificate
    privateKey = var.salesforce_private_key
  })
}

Sandbox environment

To configure a sandbox environment, add the sandbox property to json_data_encoded:

terraform Copy

resource "grafana_data_source" "salesforce_sandbox" {
  type = "grafana-salesforce-datasource"
  name = "Salesforce Sandbox"

  json_data_encoded = jsonencode({
    authType = "user"
    user     = var.salesforce_username
    sandbox  = true
  })

  secure_json_data_encoded = jsonencode({
    password      = var.salesforce_password
    securityToken = var.salesforce_security_token
    clientID      = var.salesforce_consumer_key
    clientSecret  = var.salesforce_consumer_secret
  })
}

For more information about the Grafana Terraform provider, refer to the Grafana provider documentation.