Web Server Flow with PKCE

Introduction

OAuth 2.0 Web Server Flow with Proof Key for Code Exchange (PKCE) enhances security by mitigating the risk of authorization code interception. Originally designed for mobile and single-page applications, PKCE is now commonly used for web applications to strengthen OAuth 2.0 authentication.

Learning Objectives

By the end of this tutorial, you will:

Understand the purpose of PKCE in Web Server Flow.
Learn how PKCE prevents authorization code interception attacks.
Implement Web Server Flow with PKCE in Salesforce.
Identify key differences between Web Server Flow with and without PKCE.

What is Web Server Flow with PKCE?

The Web Server Flow allows server-side applications to securely obtain an OAuth access token using a client secret. However, in certain cases where storing a client secret securely is a concern (e.g., public clients like single-page apps), PKCE enhances security by adding a dynamically generated code verifier and code challenge to the authentication request.

Why Use PKCE in Web Server Flow?

PKCE protects against authorization code interception attacks by requiring the client to prove possession of the code verifier when exchanging the authorization code for an access token. Unlike the traditional Web Server Flow, which relies on a static client secret, PKCE ensures that the client must present the original code verifier, making interception ineffective.

When to Use Web Server Flow with PKCE?

When developing public clients (e.g., mobile or JavaScript-based apps).
When additional security is required beyond the client secret.
When regulatory compliance requires secure authentication flows.

Where is PKCE Used in Salesforce?

Salesforce OAuth-enabled applications (e.g., Connected Apps).
Salesforce Experience Cloud sites using external authentication.
Any integration where additional security is necessary.

How Does Web Server Flow with PKCE Work?

1. Client Initiates Authorization Request with PKCE

The client application generates a code verifier (a random string) and a code challenge (hashed version of the verifier). It sends the authorization request with:

response_type=code
client_id=<consumer_key>
redirect_uri=<callback_url>
code_challenge=<hashed_verifier>
code_challenge_method=S256

2. User Authentication

Salesforce prompts the user to log in and approve the application.

3. Authorization Code Issued

Upon successful login, Salesforce redirects the user to the provided redirect URI with an authorization code.

4. Client Exchanges Code for Access Token

The client sends a token request, including:

grant_type=authorization_code
client_id=<consumer_key>
redirect_uri=<callback_url>
code_verifier=<original_verifier>
code=<authorization_code>

5. Salesforce Verifies and Issues Tokens

Salesforce verifies that the code verifier matches the original challenge and returns an access token and refresh token if successful.

Hands-On Implementation: Web Server Flow with PKCE in Salesforce

This guide walks you through implementing OAuth 2.0 Web Server Flow with PKCE in Salesforce. By the end, you will have a working setup where a client application can authenticate and obtain access tokens securely.

Step 1: Create a Salesforce Connected App

Navigate to: Setup → App Manager → New Connected App.
Enter the following details:
- Connected App Name: OAuth PKCE Client
- API Name: OAuth_PKCE_Client
- Contact Email: Your email
Enable OAuth Settings:
- Enable OAuth Settings
- Callback URL: https://your-app.com/callback (Use a valid redirect URL)
- OAuth Scopes:
  - Full access (full)
  - Perform requests on your behalf at any time (refresh_token, offline_access)
Require PKCE for Token Requests:
- Enable “Require Proof Key for Code Exchange (PKCE)”
Save and Copy the Consumer Key (used as client_id).

Step 2: Generate the PKCE Code Verifier and Code Challenge

PKCE requires two values:

Code Verifier: A random string (43-128 characters).
Code Challenge: A hashed and base64-encoded version of the verifier.

You can generate these values using the below link for your proof of Concept

https://developer.pingidentity.com/en/tools/pkce-code-generator.html

Step 3: Start the Authorization Request

Redirect the user to Salesforce’s authorization endpoint with the required parameters:

Authorization URL

https://login.salesforce.com/services/oauth2/authorize?
response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&code_challenge=YOUR_CODE_CHALLENGE
&code_challenge_method=S256

When the user logs in, Salesforce redirects them to YOUR_REDIRECT_URI with an authorization code.

Step 4: Exchange Authorization Code for Access Token

Once you receive the authorization code, exchange it for an access token using the code verifier.

Token Request

Send a POST request to Salesforce’s token endpoint:

POST https://login.salesforce.com/services/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&code_verifier=YOUR_CODE_VERIFIER
&code=AUTHORIZATION_CODE

Step 5: Use the Access Token

Once you receive the access token, you can use it to call Salesforce APIs.

Step 6: Refresh Token (Optional)

If your app requires a long-lived session, use the refresh token:

POST https://login.salesforce.com/services/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=YOUR_CLIENT_ID
&refresh_token=YOUR_REFRESH_TOKEN

Advantages and disadvantages

advantages

Blocks Code Interception – Ensures intercepted authorization codes are useless without the original code verifier.
No Client Secret Needed – Eliminates reliance on a client secret, making it safer for public clients.
Stronger Security, Minimal Effort – Adds robust protection with little complexity.

disadvantages

Extra Computation – Hashing and verifying the code challenge adds slight processing overhead.
Larger Requests – Extra parameters (code_challenge, code_verifier) increase request size.
Limited Legacy Support – Older OAuth setups may require updates for PKCE compatibility.

Common Mistakes and Tips

Mistake 1: Using an incorrect hashing algorithm (Only S256 is supported in Salesforce).
- Tip: Always generate a strong and random code verifier (43-128 characters).
Mistake 2: Not storing the original code verifier (Required for token exchange).
- Tip: Store the code verifier securely until the token exchange is completed.
Mistake 3: Forgetting to include code_verifier in the token request (Results in an error).
- Tip: Use HTTPS to prevent any potential attacks

Summary

PKCE enhances security by preventing code interception attacks.
No client secret is required, making it ideal for public clients.
Access tokens allow secure API calls after authentication.
Refresh tokens help maintain session longevity without reauthentication.

Quiz or Self-Assessment

What is the main security benefit of using PKCE?
What are the two main components required for PKCE?
What hashing algorithm does Salesforce support for PKCE?
What happens if the code_verifier does not match the original code_challenge?

Conclusion

Web Server Flow with PKCE is a best practice for OAuth 2.0 authentication, especially in public clients. By implementing PKCE in your Salesforce integrations, you add an extra layer of security to protect against common OAuth vulnerabilities.

Additional Resources

https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_web_server_flow.htm&type=5

Web Server Flow with PKCE