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.

Auth

See Token Exchange Handler Validation and Subject Mapping.

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

The following are methods for JWTUtil.

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.

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

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.

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:

Here’s an example payload:

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

public static Auth.JWT parseJWTFromStringWithoutValidation(String incomingJWT)

  • incomingJWT:

    Type: String

    The JWT from your identity provider.

Type:Auth.JWT

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

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

  • incomingJWT:

    Type: String

    The JWT from your identity provider.

  • certDeveloperName:

    Type: String

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

Type: Auth.JWT

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

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

  • incomingJWT:

    Type: String

    The JWT from your identity provider.

  • publicKey:

    Type: String

    The public key from your identity provider.

Type: Auth.JWT

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

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

  • 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.

Type: Auth.JWT