JWTUtil Class

Contains methods for validating a JSON Web Token (JWT) from an external identity provider as part of the OAuth 2.0 token exchange flow. Use these methods as part of the validateIncomingToken method in the Auth.Oauth2TokenExchangeHandler class.

Namespace

Auth

Usage

See Token Exchange Handler Validation and Subject Mapping.

If the methods in this class fail, Salesforce returns an Auth.JWTValidationException exception.

JWTUtil Methods

The following are methods for JWTUtil.

generateDPoPProofForToken(httpMethod, httpUri, dpopCert, nonce, token)

Generates a DPoP proof JWT from a public-private key pair. Use this method to help you implement the OAuth 2.0 Demonstrating Proof-of-Possession (DPoP) extension. To use this Apex method, the client certificate must be saved in the Certificate and Key Management page in Setup.

Signature

public static String generateDPoPProofForToken(String httpMethod, String httpUri, String dpopCert, String nonce, String token)

Parameters

httpMethod: Type: String; The HTTP method, such as POST or GET, of the request that will include the DPoP proof. This value is used for the htm claim in the JWT.
httpUri: Type: String; The target URI of the request that will include the DPoP proof JWT, such as https://MyCompanyName.my.salesforce.com/services/oauth2/token for a token request. Use your company's My Domain or Experience Cloud site as the base URL. This value is used for the htu claim in the JWT.
dpopCert: Type: String; The unique name of the client certificate from the Certificate and Key Management page.
nonce: Type: String; The dpop_nonce value returned from requests to the token endpoint. Salesforce requires a nonce for every request. This value is used for the nonce claim in the JWT. For initial token requests, where you don't have a nonce yet, use null.
token: Type: String; The DPoP-bound access token or refresh token for resource requests and refresh token flows. For token requests, use null. For resource requests, Salesforce automatically hashes the token that you provide and stores the value in the ath claim in the JWT.

Return Value

Type: String

Returns a Base64-encoded DPoP proof JWT. The JWT consists of a header and payload. For a detailed description of all claims, see the DPoP Proof JWTs section in RFC 9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP).

Here's an example header:

{
  "alg": "ES256",
  "jwk": {
    "crv": "P-256",
    "kty": "EC",
    "x": "vCAiGjuhIeMCTEJq_N9-oJRjPTRENezkoQ5TBaJtK7Y",
    "y": "YXWanpPri_6o2virYzsAfVNZhAW3SQaxFSBcs89BC-Q"
  },
  "typ": "dpop+jwt"
}

Here's an example payload:

{
  "jti": "uzUwriQThuMBtwG9CSQxHHMY",
  "htm": "POST",
  "htu": "https://MyCompany.my.salesforce.com/services/oauth2/userinfo",
  "iat": 1787773633,
  "ath": "LT0...",
  "nonce": "ni4..."
}

parseJWTFromStringWithoutValidation(incomingJWT)

Parses a JWT from an encoded string into a header, payload, and signature. Use this method to decode the JWT without validating it.

Signature

public static Auth.JWT parseJWTFromStringWithoutValidation(String incomingJWT)

Parameters

incomingJWT:
Type: String

The JWT from your identity provider.

Return Value

Type:Auth.JWT

validateJWTWithCert(incomingJWT, certDeveloperName)

Parses and validates the JWT using a certificate saved in Salesforce. The certificate can be self-signed or signed by a certificate authority.

Signature

public static Auth.JWT validateJWTWithCert(String incomingJWT, String certDeveloperName)

Parameters

incomingJWT:
Type: String

The JWT from your identity provider.
certDeveloperName:
Type: String

A certificate saved in the Certificate and Key Management page in Setup.

Return Value

Type: Auth.JWT

validateJWTWithKey(incomingJWT, publicKey)

Parses and validates the JWT using a public key from the external identity provider.

Signature

public static Auth.JWT validateJWTWithKey(String incomingJWT, String publicKey)

Parameters

incomingJWT:
Type: String

The JWT from your identity provider.
publicKey:
Type: String

The public key from your identity provider.

Return Value

Type: Auth.JWT

validateJWTWithKeysEndpoint(incomingJWT, keysEndpoint, shouldUseCache)

Parses and validates the JWT using a remote JSON Web Key Set (JWKS) endpoint on your external identity provider.

Signature

public static Auth.JWT validateJWTWithKeysEndpoint(String incomingJWT, String keysEndpoint, Boolean shouldUseCache)

Parameters

incomingJWT:
Type: String

The JWT from your identity provider.
keysEndpoint:
Type: String

A URL pointing to a valid JSON Web Key Set (JWKS) endpoint on your identity provider. The JWKS returned by the endpoint must conform to the specification defined in RFC 7517: JSON Web Key (JWK). To test HTTP callouts to the JWKS endpoint, use the Auth.HttpCalloutMockUtil class.
shouldUseCache:
Type: Boolean

Indicates whether the cache is overwritten with the JWKS after validation. If false, the cache is overwritten with the JWKS after each successful JWT validation. If true, the JWKS is cached only if there is no existing JWKS in the cache; if there is a cached JWKS, it isn't overwritten.

Return Value

Type: Auth.JWT