Add OAuth Client Credentials flow for command-line batch mode

[ponpoke]

Summary

Adds OAuth 2.0 Client Credentials Flow support for Data Loader command-line batch mode using External Client App credentials.

Addresses #1658.

Motivation

Data Loader command-line batch mode currently supports username/password authentication or interactive OAuth authentication.

For unattended service-to-service batch jobs, interactive browser authentication is not suitable. This change adds an opt-in OAuth 2.0 Client Credentials Flow while preserving the existing authentication behavior by default.

Configuration

Enable the flow with:

sfdc.oauth.flow=client_credentials

sfdc.oauth.Production.eca.clientid=<client-id>
sfdc.oauth.Production.eca.clientsecret=<encrypted-client-secret>

process.encryptionKeyFile=<key-file>

This reuses the existing External Client App configuration and Data Loader encryption mechanisms.

When sfdc.oauth.flow is not specified, the existing authentication behavior remains unchanged.

Unsupported non-empty OAuth flow values are rejected with a configuration error.

Setup and usage

1. Create an External Client App

In Salesforce Setup:

1. Go to External Client App Manager.
2. Click New External Client App.
3. Configure the basic application information.
4. Enable OAuth.
5. Add the api OAuth scope.
6. Enable Client Credentials Flow.

For example:

• OAuth Scope: Manage user data via APIs (api)
• Enable Client Credentials Flow: Enabled

A callback URL may be required when configuring OAuth, although it is not used by the Client Credentials Flow itself.

2. Configure the Client Credentials policy

Open the External Client App and configure its policy:

• Enable Client Credentials Flow: Enabled
• Run As: Select the Salesforce user that Data Loader should run as
• IP Relaxation: Configure according to the organization's security policy

Data Loader operations run with the permissions of the configured Run As user.

That user must therefore have the required object, field, and operation permissions for the Data Loader process.

3. Get the client credentials

From the External Client App settings, obtain:

• Consumer Key
• Consumer Secret

The Consumer Key is used as the client ID.

The Consumer Secret should be encrypted using Data Loader's existing encrypt.bat utility before storing it in config.properties.

4. Create an encryption key

From the Data Loader bin directory:

.\encrypt.bat -k "C:\Users\username\dataloaderconfig\dataloader.key"

This creates the encryption key used to protect the Consumer Secret.

The key file should be stored securely and must not be committed to source control.

5. Encrypt the Consumer Secret

Encrypt the Consumer Secret:

.\encrypt.bat -e "YOUR_CONSUMER_SECRET" "C:\Users\username\dataloaderconfig\dataloader.key"

Copy the encrypted output into config.properties.

Only the Consumer Secret is encrypted. The Consumer Key is stored as-is.

6. Configure config.properties

Example:

sfdc.oauth.flow=client_credentials

sfdc.oauth.Production.eca.clientid=YOUR_CONSUMER_KEY
sfdc.oauth.Production.eca.clientsecret=YOUR_ENCRYPTED_CONSUMER_SECRET

process.encryptionKeyFile=C:/Users/username/dataloaderconfig/dataloader.key

Using / in Windows paths is recommended in Java .properties files.

Alternatively, backslashes must be escaped:

process.encryptionKeyFile=C:\\Users\\username\\dataloaderconfig\\dataloader.key

For Client Credentials Flow, sfdc.username and sfdc.password are not required.

7. Run the existing batch process

Existing Data Loader command-line invocation remains unchanged:

.\process.bat "C:\Users\username\dataloaderconfig" accountInsert

For example, an extract process can be run with:

.\process.bat "C:\Users\username\dataloaderconfig" csvAccountExtractProcess

On successful authentication, the log contains:

OAuth Client Credentials Flow completed successfully using External Client App

followed by the normal Salesforce session establishment.

No interactive browser login or username/password authentication is required.

Implementation

• Adds sfdc.oauth.flow=client_credentials as a read-only configuration option.
• Reuses the existing External Client App client ID and encrypted client secret configuration.
• Exchanges the configured client credentials at the Salesforce OAuth token endpoint.
• Passes the returned access token and instance URL into the existing Data Loader session flow.
• Skips username/password requirements only when Client Credentials Flow is explicitly selected.
• Rejects unsupported explicit OAuth flow values.
• Preserves the existing authentication behavior when sfdc.oauth.flow is not configured.
• Adds tests for successful token exchange, missing client secret, rejected token requests, and read-only configuration behavior.

Test results

Tested with Eclipse Temurin JDK 17.0.19 on Windows.

Client Credentials related tests:

• AppConfigEdgeTest: 8/8 passed
• OAuthClientCredentialsFlowTest: 3/3 passed

Full unit test suite (mvn clean package, using UTF-8 and an English JVM locale):

• Tests run: 234
• Failures: 1
• Errors: 0
• Skipped: 1

The remaining failure is the pre-existing Windows-specific AppUtilTest.testExec test. It attempts to execute echo directly, but echo is a Windows shell built-in rather than a standalone executable.

That test is unchanged by this pull request.

No failures were observed in tests related to this change.

Manual E2E validation

Validated against a Salesforce org using:

• External Client App
• OAuth 2.0 Client Credentials Flow
• Encrypted client secret
• Windows command-line batch mode
• Existing process.bat command
• Bulk API 2.0 query

Result:

• OAuth Client Credentials Flow completed successfully
• Salesforce session established successfully
• API v67.0 operation executed
• 83 Account records extracted
• 83 successes
• 0 errors
• No interactive browser login
• No username/password authentication

Backward compatibility

This feature is opt-in.

When:

sfdc.oauth.flow=client_credentials

is not configured, Data Loader continues to use the existing authentication behavior.

Existing username/password authentication and interactive OAuth behavior are unchanged.

[salesforce-cla]

Thanks for the contribution! Before we can merge this, we need @ponpoke to sign the Salesforce Inc. Contributor License Agreement.