Secure Your Connected Apps and External Client Apps

Proof Key for Code Exchange

PKCE (Proof Key for Code Exchange) protects the OAuth authorization code flow against interception attacks on authorization code, especially for public clients, like mobile apps. Partners must enable PKCE in the OAuth settings of their Salesforce Connected Apps and ECAs, regardless of whether the client is public or confidential.

For Public Clients, the token exchange request must not include the client_secret parameter. The presence of the correct code_verifier parameter is the only mechanism for verifying the client's identity.

For Confidential Clients, the token exchange request must include both the code_verifier parameter, for code binding, and the client_secret parameter, for client authentication, in the /services/oauth2/token endpoint request.

Partners must also make sure that they implement the client changes referenced below. After PKCE is enabled, the Partner Application’s Connected Apps and ECAs won't work unless the client changes listed below are implemented.

Client changes:

• Generate code_verifier parameter: Create a high-entropy, random string (43-128 chars).
• Create code_challenge parameter: Hash the code_verifier, using SHA256 and BASE64URL to encode it.
• Authorization request: Include code_challenge and code_challenge_method=S256 parameters in the request to the authorization server.
• Token request: Send the original code_verifier parameter, not the hash, when exchanging the authorization code for an access token.

For more information, see Enabling PKCE for OAuth for Salesforce External Client and Connected Apps and Proof Key for Code Exchange (PKCE) Extension.

Refresh Token Rotation

Refresh Token Rotation (RTR) enhances security by invalidating the old refresh token, and replacing it with a new refresh token, after a new access token is issued. Stolen tokens are invalidated upon the next refresh token flow, which limits the window of opportunity for an attacker if a refresh token is compromised. It's a critical defense against long-term session hijacking.

Partners must have RTR enabled in the OAuth settings of all of their Salesforce Connected Apps and ECAs.

Partners must also make sure that they implement the client changes referenced below. After RTR is enabled, the Partner Application’s Connected Apps and ECAs won't work unless the client changes listed below are implemented.

Client changes:

• Implement code changes to capture the new refresh token returned by the refresh token flow and store the new refresh token securely.
• Implement robust error handling to detect when a refresh token is rejected. Sometimes a failed refresh token flow indicates that the token was compromised.
• Applications that make parallel refresh token flow requests may encounter potential race conditions where multiple requests try to use the same, about-to-be-invalidated refresh token. Your client implementation should handle potential race conditions.

For more information, see Force one-time-use Refresh Tokens - (RTR) Refresh Token Rotation and OAuth 2.0 Refresh Token Flow for Renewed Sessions.

Refresh Token 30-Day Idle Timeout

A refresh token time-to-live (TTL) defines the maximum time a refresh token remains valid. Implementing a shorter TTL for refresh tokens is a critical security measure that significantly reduces the window of opportunity for an attacker. By limiting the duration of a potential compromise, you can prevent unauthorized users from maintaining indefinite access to a system. Ultimately, these shorter expirations mitigate the risk of long-term persistence, ensuring that security remains tight and access stays within the hands of legitimate users.

It is important to keep the TTL for the refresh token as short as possible. With this security control Salesforce invalidates the idle refresh token after 30 days.

Implementation:

To turn on the control, go to the OAuth settings of your ECA or Connected App. Select Limit Idle Refresh Token Time-to-Live (TTL) to 30 Days.

Client changes:

• Each time a token is used within the 30 day-period, the idle TTL resets.
• To avoid re-authorizing, clients can initialize a refresh token flow before the 30-day limit and receive a new refresh token with a further 30-day TTL.

For more information, see Limit the Idle Refresh Token TTL in External Client Apps and Limit Idle Refresh Token Time-to-Live (TTL) in Connected Apps.

Allowlist Ranges for Refresh Tokens

The Refresh Token IP Allowlist control provides an additional security layer by ensuring refresh token requests can originate only from a predefined set of allowed IP ranges owned by the client. This enforcement immediately rejects refresh token use from unknown IP addresses by blocking threat actors from using compromised tokens.

ECAs and Connected Apps using the Web Server flow should only request new tokens from your allowed IP ranges. As an ISV, you should identify these specific ranges and update your app configuration accordingly. Once configured, Salesforce automatically blocks any token requests originating from outside the allowed IP ranges.

Implementation:

To turn on the control, go to the OAuth settings of your ECA or Connected App. Turn on Enforce Refresh Token IP Allowlist.

• Configuration: In the Refresh Token IP Allowlist section of the configuration, add your IP ranges. The system automatically validates the request IP against these stored ranges during the token exchange process.
• IP Range Guidance: In general, avoid broad IP ranges. A total of 256 IP addresses are allowed across all IP ranges.
• Avoid configuring multiple callback URLs that have a mixed purpose. For example: avoid configuring HTTPS URL and a custom URL scheme as callback URLs for the same app.

For more information, see Set IP Allowlist Ranges for Refresh Tokens.

Review and Lock Security Controls

After all changes are implemented, ISVs must self-attest that the app is onboarded to all four security controls and all relevant client changes are complete. After the attestation is made, the security controls are locked and can’t be disabled. ISVs are allowed to update the IP ranges in the Connected App or ECA configuration if needed.

To self-attest and lock the security controls, click Review Controls at the top of the Connected App or ECA setup page. Select the controls you want to enforce. Note that only the controls that have been implemented appear on the self-attestation modal. Select Confirm.

The Review Controls banner is only available when at least one of the security controls is turned on.

For ECAs:

For Connected Apps:

Deadlines for Implementation

All Partners must implement the preceding requirements for Connected Apps and ECAs by the deadlines set forth below.

Report Suspicious Activity

Any suspicious activity or security incidents that impact a Partner’s applications or solutions and/or the customer integrations with a Partner’s applications or solutions must be reported by the Partner immediately to the Salesforce security team by emailing security@salesforce.com for further investigation.