Salesforce Connection Management

Overview

Speediful supports two authentication methods for connecting to Salesforce:

Method	Description
JWT Bearer	OAuth JWT Bearer flow via Salesforce External Client App
Security Token	Username, password, and security token via SOAP login()

Both methods use SLAM_add_connection. The @auth_method parameter selects between them.

The SLAM_add_connection command validates, stores and activates a Salesforce connection for use by the SQL Server Service Account. The connection details include the Salesforce API version, which is used for all future operations with this username. By default, a connection test is performed and the connection will only be stored if this test passes. The connection test can be skipped.

JWT-based authentication provides more in-depth security. When transitioning from security token based authentication to JWT-based authentication, it can be helpful to understand the parallels, both in terms of what data is needed and what the system requires.

Category	Dimension	JWT Bearer	Security Token
Data	Identity	Salesforce Username	Salesforce Username
Data	Secret	Private Key (.pem file)	Salesforce Password and Security Token
Data	Secret protection	Private Key passphrase (optional but strongly recommended)	-
Data	Server-side trust	Corresponding certificate (.crt uploaded to Salesforce)	-
Data	App identifier	Consumer Key (from External Client App)	-
System	Active user	Required	Required
System	Setup	External Client App must be active with OAuth and JWT Bearer Flow enabled	SOAP API login() must be enabled and Use Any API Auth user permission (required for orgs created since Summer '26)
System	Access	User must have access to the External Client App (via Profile or Permission Set)	API version 64.0 or lower, and org on Spring '27 release or earlier
System	Certificate validity	Certificate must not be expired	-

important

Object, record, field and data access depends on the policies applied to Salesforce, which is usually administered via Profiles, Permission Sets and Permission Set Groups. Certain feature licenses or user attributes may also be required. Troubleshooting of access should be in consultation with the Salesforce administrator and Salesforce documentation. It is recommended to review and apply these permissions where appropriate:

• Object level permissions
• View All Data permission
• Modify All Data permission
• Field level security
• View Encrypted Data

JWT Bearer Authentication

JWT Bearer authentication uses a certificate-based OAuth flow, eliminating the need for passwords and security tokens. This is the recommended approach for new connections.

How JWT Authentication Works

JWT authentication uses a pair of cryptographic files and a Consumer Key instead of a password:

• Private key (.pem file) - stays on your server and is used by Speediful to prove its identity to Salesforce. This file is the equivalent of a password. Treat it with the same level of security. Anyone with access to this file can authenticate as the associated Salesforce user.
• Certificate (.crt file) - uploaded to Salesforce. This is the public counterpart to the private key and is safe to share. Salesforce uses it to verify that requests are genuinely coming from the holder of the private key.
• Consumer Key (Client ID) - a unique identifier for your Salesforce External Client App. The Consumer Key tells Salesforce which app is requesting access. On its own, the Consumer Key cannot authenticate as it must be paired with a valid private key. It is not a secret, but best kept internal.

Both cryptographic files are generated together by SLAM_setup_jwt and stored in C:\ProgramData\Speediful\SLAM\keys\. The Consumer Key is obtained from the External Client App settings in Salesforce (see Step 2).

warning

Protect the private key. The .pem file should be secured with the same care as a password. Do not copy it to shared drives, email it, or commit it to source control. Only the SQL Server service account needs access to this file.

JWT Setup Overview

In order to use JWT-based authentication, you must follow three main steps. This guide walks you through the entire process:

1. Create a pair of crytographic key files
2. Create a Salesforce External Client App configured for JWT Bearer flow and the certificate from step 1
3. Create the connection with the private key from step 1 and the Consumer Key from step 2

Step 1: Generate a JWT Keypair

Use SLAM_setup_jwt to generate a private key and self-signed certificate:

EXEC dbo.SLAM_setup_jwt
    @key_name = 'acme-prod',                 -- A name to identify this keypair
    @password = 'your_strong_passphrase'     -- Encrypts the private key (highly recommended)

Parameter	Type	Default	Description
@key_name	VARCHAR	NULL	Strongly recommended. Name for the keypair. e.g. 'acme-partial'. Files are saved as {key_name}.pem and {key_name}.crt. If NULL, defaults to the machine hostname
@password	VARCHAR	NULL	Strongly recommended. Passphrase used to encrypt the private key. Use a unique passphrase (not your Salesforce password). You'll use this value again for in @key_password to SLAM_add_connection
@cert_days	INT	365	Number of days until the certificate expires
@force	BIT	0	When set to 1, overwrite an existing keypair with the same name

The certificate file will be saved to C:\ProgramData\Speediful\SLAM\keys\. Upload this certificate to your Salesforce External Client App in the next step.

warning

It is strongly recommeneded to adhere to these security best practices:

Use a unique @key_name per Salesforce org such as 'acme-prod' / 'acme-full' / 'nto-partial'. Re-using private keys and certificates across multiple orgs is analogous to reusing the same password. A compromise of the private key affects all orgs that share it. By using unique key pairs, the private key can only access one system. Furthermore, re-generating a new key pair for the org (commonly referred to as "rotating keys") will not invalidate your cryptographic key data used to authenticate to other orgs.

Set a @password whenever possible and make it different from the Salesforce password. An unencrypted private key file is analogous to a plaintext password sitting on disk. Encrypting it with a passphrase ensures that simply obtaining the private key file is not enough to authenticate as the Salesforce user.

Step 2: Configure Salesforce External Client App

In Salesforce Setup, create a new External Client App and configure the following settings across each page.

Under Basic Information

• Set the required fields as you prefer
• Keep the Distribution State as "Local"

Under API (Enable OAuth Settings) (subsequently labelled OAuth Settings)

1. Check to Enable OAuth
2. Set the Callback URL to https://0.0.0.0 (this URL is not used by JWT, but Salesforce requires a value)
3. Add the following OAuth Scopes:
   • Perform requests at any time (refresh_token, offline_access)
   • Manage user data via APIs (api)
4. Under Flow Enablement:
   • Enable JWT Bearer Flow and upload the .crt certificate file generated in Step 1
5. Under Security, enable all of the following:
   • Require Secret for Web Server Flow
   • Require Secret for Refresh Token Flow
   • Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows
6. Click Create / Save

Policies Page:

1. Under Plugin Policies, set Permitted Users to Admin approved users are pre-authorized
2. Scroll up and add the Profiles or Permission Sets whose members should be authorized to connect via JWT. The Salesforce user specified in @username below must have one of the selected profiles or permission sets
3. Review the App Authorization settings and adjust to match your company policy
4. Save

Settings Page:

1. Under OAuth Settings > App Settings, click to reveal the Consumer Key. You will need this value for Step 3

Step 3: Add the JWT Connection

EXEC dbo.SLAM_add_connection
    @username = 'your_username@company.com',
    @auth_method = 'jwt_bearer',
    @consumer_key = '3MVxxxxxxxxxxxxxxxxxxxxxxx',
    @key_name = 'acme-prod',
    @key_password = 'your_strong_passphrase',  -- Required if the keypair was created with @password
    @domain = 'login'                          -- or 'test' for sandboxes, or custom domain

Parameter	Type	Default	Description
@username	VARCHAR	Required	Salesforce username
@auth_method	VARCHAR	'security_token'	Authentication method. Use 'jwt_bearer' for JWT-based auth
@consumer_key	VARCHAR	NULL	Consumer Key (Client ID) from the Salesforce External Client App. Required for jwt_bearer
@key_name	VARCHAR	NULL	Name of the keypair generated by SLAM_setup_jwt. Required for jwt_bearer
@key_password	VARCHAR	NULL	Passphrase that decrypts the private key. Required when the keypair was generated with a @password
@domain	VARCHAR	'login'	Salesforce login domain: 'login', 'test' (sandboxes), or custom domain
@environment_name	VARCHAR	NULL	Optional alias for this environment
@api_version	INT	60	Salesforce API version
@skip_test	BIT	0	Skip connection test when set to 1

warning

The added connection is automatically activated for use in all future operations. The active Salesforce username is stored in field SLAM_Settings.Username

Custom Domains can be specified by providing the login subdomain that preceeds the ".salesforce.com" portion of the URL, for example:

• Sandboxes: @domain = 'acmecorp--partial.sandbox.my' to log into acmecorp's sandbox named 'partial'
• Production: @domain = 'acmecorp.my'

Certificate Expiration

JWT certificates have a limited validity period (default: 365 days, controlled by @cert_days). When a certificate expires, JWT authentication will fail and the certificate must be renewed.

To renew an expired certificate:

1. Create a new keypair. Use the same @key_name when possible:

-- @force is not needed for expired certificates
EXEC dbo.SLAM_setup_jwt
    @key_name = 'acme-prod',
    @password = 'your_strong_passphrase'     -- Encrypts the new private key (highly recommended)

2. Upload the new .crt file to your Salesforce External Client App (replacing the old certificate)

If you reused the same @key_name and @password as before you're all done. If you used a new @key_name or @password, or are unsure, recreate the connection with SLAM_add_connection.

tip

Speediful will warn you when attempting to generate a keypair if a valid (non-expired) certificate already exists. Use @force = 1 to regenerate before expiration if needed.

Remove a JWT Keypair

This command deletes the private key and certificate files from this machine. This will prevent this machine from authenticating to the associated Salesforce org via JWT.

warning

Removing the keypair from this machine does not revoke access to Salesforce. If the private key was copied elsewhere, it can still be used to authenticate until you take action in Salesforce. To fully revoke access, either deactivate the External Client App or replace the certificate with a new one.

EXEC dbo.SLAM_remove_jwt @key_name = 'acme-prod'

Parameter	Type	Default	Description
@key_name	VARCHAR	Required	Name of the keypair to remove

Security Token Authentication

warning

Migrate to JWT Bearer authentication before the Summer '27 release. Security Token authentication relies on SOAP API login(), which Salesforce is retiring. Key impacts:

• SOAP API login() is not available in API versions 65.0 and later
• SOAP API login() is disabled by default in newly created orgs and must be explicitly enabled by an admin
• From Summer '26, newly created orgs additionally require users to have the Use Any API Auth user permission to authenticate via SOAP API login(). Existing orgs may optionally enable this enforcement
• After the Summer '27 retirement, any integration still using SOAP API login() will fail to authenticate, and all subsequent API calls will fail

See Salesforce's Platform SOAP API login() Retirement article for details.

warning

Orgs created since Summer '26 must enable SOAP API login() before attempting to add a connection.

EXEC dbo.SLAM_add_connection
    @username = 'your_username@company.com',    -- Required
    @password = 'your_password',                -- Required
    @token = 'your_security_token',             -- Required
    @domain = 'login'                           -- Optional (default: 'login')

Parameter	Type	Default	Description
@username	VARCHAR	Required	Salesforce username
@password	VARCHAR	Required	Salesforce password
@token	VARCHAR	Required	Salesforce security token
@domain	VARCHAR	'login'	Salesforce login domain: 'login', 'test' (sandboxes), or custom domain
@environment_name	VARCHAR	NULL	Optional alias for this environment
@api_version	INT	60	Salesforce API version
@skip_test	BIT	0	Skip connection test when set to 1

warning

The added connection is automatically activated for use in all future operations. The active Salesforce username is stored in field SLAM_Settings.Username

Custom Domains can be specified by providing the login subdomain that preceeds the ".salesforce.com" portion of the URL, for example:

• Sandboxes: @domain = 'acmecorp--partial.sandbox.my' to log into acmecorp's sandbox named 'partial'
• Production: @domain = 'acmecorp.my'

Managing Connections

List Available Connections

Prints the available connections

EXEC dbo.SLAM_list_connections

Set Active Connection

Activating a connecting sets it as the Salesforce user for all future operations. This simply updates the value Username in table SLAM_Settings

EXEC dbo.SLAM_use_connection_username @username = 'your_username@company.com'

SELECT * FROM SLAM_Settings -- Username is set to your_username@company.com for all future operations

Test Connection

Confirms a stored credential is valid by performing a login operation. The connection test will fail if the credentials are invalid or if the password has expired.

EXEC dbo.SLAM_test_connection @username = 'your_username@company.com'

Remove Connection

Deletes a stored credential

EXEC dbo.SLAM_remove_connection @username = 'your_username@company.com'