Implementing a Token Exchange Handler is identity-layer work that requires Apex skills, OAuth knowledge, and careful security review. The walkthrough below covers the standard implementation flow from initial design through production registration.
- Design the exchange scenario and security model
Document what the exchange is supposed to accomplish, the trusted issuer of the subject token, the claims to validate, the mapping rule from claims to Salesforce user, and the audit requirements. Review the design with the org's security team. Identify any compliance constraints (SOX, HIPAA, regional privacy laws) that affect the handler's behavior. Approve the design before writing code; identity-layer code that gets implemented before design review usually has security gaps that surface during audit.
- Implement the Apex handler class
Create an Apex class extending Auth.TokenExchangeHandler. Implement validateToken to verify the subject token's signature against a trusted JWKS, check issuer and audience, and validate expiration. Implement validateAndExchangeToken to perform the validation and then look up or provision the matching Salesforce user. Return the appropriate response token. Cover the implementation with unit tests targeting at least 90% coverage and explicitly testing every failure mode (invalid signature, expired token, missing claim, no matching user).
- Register the handler in Setup
From Setup, navigate to Token Exchange Handlers and click New. Provide a name, a description, the Apex class reference, and the endpoint configuration the handler should respond to. Configure the trusted issuer details (JWKS URL, allowed audiences). Save and enable the handler. Test by sending a sample token exchange request from a test client and verifying the returned token works for subsequent API calls. Iterate until the test cases from the design document all pass.
- Promote to production with security signoff
Schedule production deployment during a low-traffic window. Deploy the Apex class through the standard pipeline (Change Sets, DevOps Center, or SFDX). Register the handler in production with the production trusted issuer details. Run an end-to-end test from a production client and confirm the exchange works as designed. Update the org's identity architecture documentation with the new handler, its purpose, and its security model. Schedule a six-month review of the handler against new threat models and new OAuth specifications.
- Token signature validation must use the trusted issuer's public keys from a JWKS endpoint. Hardcoding a single public key breaks when the issuer rotates keys.
- Audience verification is mandatory. A handler that does not check the audience claim accepts tokens intended for other systems, which is a serious vulnerability.
- Error responses must not leak internal information. Return generic 401 Unauthorized for any validation failure, log details internally for debugging.
- On-demand user provisioning needs governance. A handler that creates a new user for every unknown subject token quickly fills the org with stale accounts.
- Handler classes run synchronously in the token exchange request path. Slow validation logic times out the exchange and breaks client integrations.