JWT Token Flow

Introduction

JWT (JSON Web Token) Bearer Token Flow is an OAuth 2.0 authentication mechanism in Salesforce, often used for server-to-server integrations without requiring interactive user authentication. It enables secure API access by exchanging a signed JWT for an access token.

This flow is particularly useful in scenarios where a client application needs to authenticate as a user without their direct involvement.

Learning Objectives

By the end of this tutorial, you will:

• Understand what the JWT Token Flow is and when to use it.
• Learn how JWT authentication works in Salesforce.
• Implement JWT Token Flow in Salesforce using a Connected App.
• Avoid common mistakes in JWT authentication.

What is JWT Token Flow?

JWT Token Flow is an OAuth 2.0 authentication method in which a client application presents a signed JWT to obtain an access token. This allows secure, non-interactive authentication, making it ideal for backend integrations.

When to Use JWT Token Flow?

• When a client application needs to authenticate as a user without requiring a password.
• For server-to-server communication where interactive login is not feasible.
• When using Salesforce APIs securely without relying on refresh tokens.

How JWT Token Flow Works in Salesforce

The process involves the following steps:

Step 1: Create a Connected App in Salesforce

1. Navigate to Setup → App Manager.
2. Click New Connected App.
3. Provide a name and API Name.
4. Enable OAuth Settings and select “Use digital signatures”.
5. Upload a public key for JWT signature verification.
6. Choose OAuth scopes like “Full access (full)” or “Perform requests on your behalf at any time (refresh_token, offline_access)”.
7. Save and note down the Consumer Key.

Step 2: Generate a Private Key and Public Certificate

Use OpenSSL to generate a private key and certificate:

openssl genrsa -out private.key 2048
openssl req -new -x509 -key private.key -out public.crt -days 365

Upload public.crt to the Salesforce Connected App.

Step 3: Construct the JWT Token

The JWT structure consists of:

• Header (Algorithm & Token Type)
• Payload (Claims like iss, sub, aud, and exp)
• Signature (Generated using the private key)

Example JWT header:

{
  "alg": "RS256",
  "typ": "JWT"
}

Example JWT payload:

{
  "iss": "Your_Consumer_Key",
  "sub": "Salesforce_User_Username",
  "aud": "https://login.salesforce.com",
  "exp": 1712345678
}

Step 4: Sign the JWT

Use a JWT library to sign the token with the private key:

openssl dgst -sha256 -sign private.key jwt_header_payload.json | base64

Alternatively, in Node.js:

const jwt = require('jsonwebtoken');
const fs = require('fs');

const privateKey = fs.readFileSync('private.key');

const token = jwt.sign(
  {
    iss: "Your_Consumer_Key",
    sub: "salesforce_user@example.com",
    aud: "https://login.salesforce.com",
    exp: Math.floor(Date.now() / 1000) + 300
  },
  privateKey,
  { algorithm: 'RS256' }
);

console.log(token);

Step 5: Request an Access Token from Salesforce

Make an HTTP POST request to Salesforce’s token endpoint:

curl -X POST https://login.salesforce.com/services/oauth2/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=YOUR_SIGNED_JWT"

Step 6: Use the Access Token

Upon successful authentication, Salesforce returns an access token:

{
  "access_token": "00Dxx0000000000AAA",
  "instance_url": "https://your-instance.salesforce.com",
  "token_type": "Bearer"
}

Use this token to make API requests:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://your-instance.salesforce.com/services/data/v59.0/sobjects/Account/

Advantages and disadvantages

advantages

• No User Interaction Needed – Ideal for server-to-server authentication without manual login.
• Highly Secure – Uses digital signatures (RS256) to prevent credential leaks.
• No Refresh Tokens – Eliminates the risk of refresh token exposure.

disadvantages

• Complex Setup – Requires key management and proper configuration.
• Key Exposure Risk – If the private key is compromised, security is breached.
• Short-lived Tokens – Requires frequent regeneration, adding processing overhead

Common Mistakes and Tips

• Mistake 1: Incorrect JWT Signing
  • Tip: Ensure you are using RS256 and the correct private key.
• Mistake 2: Expired JWT
  • Tip: The exp claim should be within 5 minutes of the request.
• Mistake 3 :Mismatched sub (Subject Claim)
  • Tip: The sub should be an existing Salesforce username with the right permissions.
• Mistake 4 : Incorrect aud (Audience Claim)
  • Tip: Use:
    • "https://login.salesforce.com" for production.
    • "https://test.salesforce.com" for sandbox.
• Mistake 5: Connected App Settings
  • Tip: Ensure “Admin approved users are pre-authorized” is enabled in the Connected App Policies.

Summary

• JWT Token Flow enables secure, non-interactive authentication in Salesforce.
• A Connected App with a digital signature is required.
• The JWT consists of a header, payload, and signature.
• A signed JWT is exchanged for an access token via Salesforce’s token endpoint.
• The access token allows API interactions without requiring user credentials.

Quiz / Self-Assessment

1. What is the primary benefit of using JWT Token Flow in Salesforce?
2. What algorithm must be used to sign the JWT?
3. What are the key claims in the JWT payload?
4. What Salesforce setting is required for a JWT-based Connected App?
5. How long can a JWT be valid before it expires?

Conclusion

JWT Token Flow in Salesforce is a powerful authentication mechanism for server-to-server communication. By correctly setting up a Connected App, JWT signing process, and token exchange, you can ensure a secure and seamless integration.

Additional Resources

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