JWT vs JWT Token Exchange in Salesforce

Question

When configuring Named Credentials in Salesforce with the Identity Type set as “Named Principal,” two options for Authentication Protocol are presented: JWT and JWT Token Exchange. Many users wonder what distinguishes these two options, especially when additional attributes, such as Scope and Token Endpoint URL, appear in the JWT Token Exchange configuration.

Additionally, users often ask whether Salesforce assumes the Service Endpoint URL (configured in the URL field of Named Credentials) and the Token Endpoint URL are the same when using JWT. Here’s a detailed explanation:

Answer:

JWT in Salesforce Named Credentials:

When you select JWT as the authentication protocol, Salesforce itself generates a JWT token for you. This token is directly sent as a Bearer Token to the service endpoint URL you define in the Named Credential. Essentially, Salesforce assumes that the service you’re calling supports JWT tokens for authentication, and there is no need for an intermediary step to exchange the token for another format.

For example:

Salesforce → [JWT Bearer Token] → 3rd Party Service

Here, the service endpoint URL in the URL field represents the actual API you want to call, and there is no interaction with an external authorization service.

JWT Token Exchange in Salesforce Named Credentials:

When you select JWT Token Exchange, Salesforce first generates a JWT token and sends it to an external Authorization Service. This authorization service validates the provided JWT and exchanges it for an Access Token. Salesforce then uses the received access token as a Bearer Token to authenticate calls to the target service.

For example:

Salesforce → [JWT] → Authorization Service → [Access Token] → 3rd Party Service

This process involves two distinct endpoints:

1. Token Endpoint URL: The URL of the external authorization service where the JWT is sent for exchange.
2. Service Endpoint URL: The target API endpoint you want to call, defined in the URL field of the Named Credential.

In this case, Salesforce does not assume that the service endpoint and token endpoint URLs are the same. These are treated as two separate configurations.

When to Use Each Option?

JWT:
Use this option when the third-party service directly supports JWT tokens as a method of authorization. No external token exchange process is required.

JWT Token Exchange:
Choose this option when the third-party service does not support JWT tokens but requires a different token format (e.g., OAuth access tokens). In this scenario, an external authorization service is used to exchange Salesforce’s JWT for the required token format.

Code Example:

Below is a configuration snippet for JWT Token Exchange in Salesforce Named Credentials:

{
  "URL": "https://api.example.com/v1/resource",   // Service Endpoint URL
  "Authentication Protocol": "JWT Token Exchange",
  "Token Endpoint URL": "https://auth.example.com/token",  // Token Endpoint URL
  "Issuer": "your-issuer-id",
  "Scope": "api.read api.write",
  "Named Principal Subject": "your-user-id"
}

Explanation:
In this snippet, Salesforce will send a JWT to the Token Endpoint URL, which is the authorization server. The authorization server will exchange it for an access token with the specified Scope. This access token will then be used to call the Service Endpoint URL as the target API.

{
  "URL": "https://api.example.com/v1/resource",   // Service Endpoint URL
  "Authentication Protocol": "JWT",
  "Issuer": "your-issuer-id",
  "Named Principal Subject": "your-user-id"
}

Explanation:
Here, Salesforce directly generates a JWT and uses it as a bearer token to authenticate API calls to the Service Endpoint URL. There is no intermediate token exchange process involved.

Key Takeaways:

• Use JWT when the service directly supports JWT for authorization.
• Use JWT Token Exchange when the service requires an access token and an external authorization service is available for token exchange.
• The Token Endpoint URL and Service Endpoint URL are distinct and must be configured separately when using JWT Token Exchange.

Summing Up

In summary, when configuring Named Credentials in Salesforce, I choose JWT if the third-party service directly supports JWT tokens for authorization, as Salesforce will handle token generation and send it directly as a Bearer Token to the service. On the other hand, I use JWT Token Exchange when the service requires a different token format, and Salesforce interacts with an external authorization service to exchange the JWT for an access token. In this case, the Token Endpoint URL (for token exchange) and the Service Endpoint URL (the target API) are configured separately, ensuring flexibility in integration setups.