Proof Key for Code Exchange (PKCE) Extension
To improve the security of your OAuth and authentication provider implementations, use the OAuth 2.0 Proof Key for Code Exchange (PKCE) extension. You can require PKCE at an org-wide level, require it for a specific connected app, and automatically enable it for supported authentication providers.
Required Editions
| Available in: all editions |
During the OAuth authorization code flow and its derivatives, the PKCE extension helps ensure that the client that initiates the flow is the same client that completes the flow. During these flows, an app requests an authorization code from Salesforce, which it then exchanges for an access token. Traditionally, the app can secure the token request by including its connected app consumer secret. Because the consumer secret is information that only the app and Salesforce know, it functions as a password for accessing the Salesforce token endpoint. Even if an attacker somehow gains access to an authorization code, they can’t use it to get an access token unless they have the consumer secret.
But public clients like mobile apps and single-page apps can’t keep the consumer secret confidential. Unlike private client apps with a traditional client-server architecture, public clients don’t have a private backend where they can store the consumer secret. If a public client sends the consumer secret in the token request, it risks leaking it. For this reason, we never recommend including the consumer secret in token requests for a public client.
With no consumer secret, the app is vulnerable to an attacker intercepting the
authorization code and attempting to exchange it for an access token. PKCE
helps fill the consumer secret gap with a set of hashed parameters that only
your app and Salesforce can understand. During a flow that implements PKCE,
the app creates a random string, known as the code_verifier parameter. It then hashes this value with an
SHA-256 algorithm. This hashed value is the code_challenge parameter. A key concept of SHA-256 hashing
is that it only works one way. You can get the code_challenge from the code_verifier by running the SHA-256 algorithm. But you
can’t run it backwards to get the code_verifier from the code_challenge.
The concept of a one-way function plays an important role in why PKCE works. When
the app sends its initial request for an authorization code, it includes the
hashed code_challenge parameter. Then,
when it requests an access token, it includes the code_verifier parameter. Now,
Salesforce has both parameters, and it can run the SHA-256 algorithm on the
code_verifier value to compare
it to the code_challenge. If the values
match, Salesforce can verify that the same app sent the authorization
request and the token request. Even if an attacker has the authorization
code, they can’t exchange it for an access token because they don’t have the
PKCE parameters that only your app and Salesforce know.
We recommend that you always implement PKCE for public clients. For private clients, we recommend that you implement PKCE and include the consumer secret in token requests.
You can optionally implement PKCE by including code_challenge and code_verifier parameters when you build variations of the
authorization code flow with Salesforce. These flows support PKCE.
- Web server flow
- Hybrid web server flow
- All variations of the Authorization Code and Credentials Flow, including headless registration, headless passwordless login, and headless guest flows. See Headless Identity Flows.
To ensure that PKCE is enforced, we recommend that you take these security measures.
- Require PKCE at an org-wide level from the OAuth and OpenID Connect settings page. With this setting enabled, all authorization code flow variations that don’t use PKCE are automatically blocked.
- Require PKCE for specific connected apps. As a connected app developer, if you enable this setting, you must implement PKCE when you build authorization flows with this app.
- Use PKCE for an authentication provider. For supported authentication providers, you can automatically use PKCE by selecting a single setting. These authentication providers support PKCE.
- Generate PKCE Parameters
Use the PKCE Generator endpoint to quickly generatecode_challengeandcode_verifierparameters that you can implement in variations of the authorization code flow.
Generate PKCE Parameters
Use the PKCE Generator endpoint to quickly generate code_challenge and code_verifier parameters that
you can implement in variations of the authorization code flow.
- Enable Cross-Origin Resource Sharing (CORS) for OAuth
endpoints, which automatically enables CORS for the
/services/oauth2/pkce/generatorendpoint. - To generate the
code_challengeandcode_verifierparameters, send an HTTP GET request to the/services/oauth2/pkce/generatorendpoint on your My Domain login URL or Experience Cloud site URL. Don’t include any headers or body parameters in this request.Here’s an example request that uses a My Domain login URL.GET /services/oauth2/pkce/generator? HTTP 1.1 Host: MyDomainName.my.site.salesforce.comHere’s an example request that uses an Experience Cloud site URL.GET /services/oauth2/pkce/generator? HTTP 1.1 Host: MyDomainName.my.site.comSalesforce responds with these PKCE parameters.
Here’s an example response.Parameter Description code_challenge_methodThe method used to compute the code_challengefrom thecode_verifier. Salesforce uses theS256method, which computes thecode_challengefrom thecode_verifierusing an SHA256 algorithm. For more information, see Section 4.2 in RFC 7636: Proof Key for Code Exchange by OAuth Public Clients.code_challengeSpecifies the SHA256 hash value of the
code_verifiervalue in the token request. The value is Base-64 URL encoded as defined in Section 5 of RFC 4648: The Base16, Base32, and Base64 Data Encodings.When you configure your authorization flow, include this value in the authorization request.
code_verifierSpecifies 128 bytes of random data with high entropy to make guessing the code value difficult. Set this parameter to help prevent authorization code interception attacks. The value is Base-64 URL encoded as defined in Section 5 of RFC 4648: The Base16, Base32, and Base64 Data Encodings.
When you configure your authorization flow, include this value in the token request.
{ “code_challenge_method”:“S256” “code_challenge”:“JB7nT*************” “code_verifier”:“GkLvw**************” }
When you configure the web server flow, hybrid web server flow, and
variations of the Authorization Code and Credentials Flow, include the
code_challenge and code_verifier parameters in your requests as directed.
