OauthTokenExchangeHandler | Metadata API Developer Guide

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

Parent Type

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

OauthTokenExchangeHandler components have the suffix .oauthtokenexchangehandler and are stored in the oauthtokenexchangehandlers folder.

Version

OauthTokenExchangeHandler components are available in API version 60.0 and later.

Special Access Rules

There are no additional access requirements that are specific to this type.

Fields

Field Name	Description
description	Field Type string Description Required. A description for your token exchange handler.
developerName	Field Type string Description Required. The API name for the handler.
enablements	Field Type OauthTokenExchHandlerApp[] Description The enablement settings for the token exchange handler, including the execution user who runs the Apex class, the connected apps or external client apps for which it’s enabled, and whether or not it’s the default handler.
isAccessTokenSupported	Field Type boolean Description Required. Indicates whether the handler supports OAuth 2.0 access tokens from the identity provider, including opaque access tokens and JSON Web Token (JWT)-based access tokens.
isEnabled	Field Type boolean Description Required. Indicates whether the handler is enabled. To complete enablement, add an `enablements` field that specifies the enablement settings.
isIdTokenSupported	Field Type boolean Description Required. Indicates whether the handler supports OpenID Connect ID tokens from the identity provider.
isJwtSupported	Field Type boolean Description Required. Indicates whether the handler supports tokens from the identity provider that are in JWT format, such as JWT-based access tokens.
isProtected	Field Type boolean Description Indicates whether the handler can be linked to or referenced by components created in a subscriber org. See Protected Components in Managed Packages.
isRefreshTokenSupported	Field Type boolean Description Required. Indicates whether the handler supports OAuth 2.0 refresh tokens from the identity provider.
isSaml2Supported	Field Type boolean Description Required. Indicates whether the handler supports SAML 2.0 assertions from the identity provider.
isUserCreationAllowed	Field Type boolean Description Required. Indicates whether the handler can set up new users. During the token exchange flow, the Apex handler maps users from the identity provider to Salesforce. If the isUserCreationAllowed field is `true`, the `canCreateUser` boolean in the `getUserForTokenSubject` method is `true`, and the user doesn’t exist in Salesforce, the handler sets up a new User object, which Salesforce automatically inserts to finish creating the user.
masterLabel	Field Type string Description Required. The label of the token exchange handler record.
tokenHandlerApex	Field Type string Description Required. The Apex class associated with the token exchange handler. The class contains methods to validate the token and map users to Salesforce. It must extend the `Oauth2TokenExchangeHandler` Apex class.

OauthTokenExchHandlerApp

Represents the settings for a specific Salesforce connected app or external client app that’s enabled for the token exchange handler. A handler can be enabled for multiple apps.

Field Name	Description
apexExecutionUser	Field Type string Description Required. A user who runs the Apex token exchange handler. We recommend that you use an integration user.
connectedApp	Field Type string Description The API name of the connected app that’s being used to integrate with Salesforce.
externalClientApp	Field Type string Description The API name of the external client app that’s being used to integrate with Salesforce.
isDefault	Field Type boolean Description Required. Indicates whether the token exchange handler is the default handler for this app. During the token exchange flow, in the token request, you can optionally include a `token_handler` parameter with the name of a specific handler’s Apex class. If you don’t include this parameter, Salesforce defaults to the default handler.

Declarative Metadata Sample Definition

The following is an example of an OauthTokenExchangeHandler component.

<?xml version="1.0" encoding="UTF-8"?>
<OauthTokenExchangeHandler xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>MyTokenExchangeHandler</developerName>
    <description>My token exchange handler</description>
    <isAccessTokenSupported>true</isAccessTokenSupported>
    <isEnabled>true</isEnabled>
    <isIdTokenSupported>false</isIdTokenSupported>
    <isJwtSupported>true</isJwtSupported>
    <isProtected>false</isProtected>
    <isRefreshTokenSupported>false</isRefreshTokenSupported>
    <isSaml2Supported>false</isSaml2Supported>
    <isUserCreationAllowed>true</isUserCreationAllowed>
    <masterLabel>MyTokenExchangeHandler</masterLabel>
    <tokenHandlerApex>MyOauthTokenExchangeHandler</tokenHandlerApex>
    <enablements>
        <apexExecutionUser>integrationuser@mycompany.com</apexExecutionUser>
        <connectedApp>TokenExchangeApp1</conectedApp>
        <isDefault>true</isDefault>
    </enablements>
</OauthTokenExchangeHandler>

The following is an example package.xml that references the previous definition.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>OauthTokenExchangeHandler</name>
    </types>
    <version>60.0</version>
</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.

Login

Products

Experiences

Agentforce

CRM Products

Industries

Small Business

Data

Salesforce Platform

Customer Success

Partner Apps & Experts

Discover the #1 AI CRM

Discover the #1 AI CRM

Automotive

Communications

Engineering, Construction & Real Estate

Consumer Goods

Education

Energy & Utilities

Financial Services

Healthcare & Life Sciences

Manufacturing

Media

Nonprofit

Professional Services

Public Sector

Retail

Technology

Travel, Transportation & Hospitality

Explore Salesforce for industries.

Explore Salesforce for industries.

Customer Stories

Salesforce on Salesforce Stories

Trailblazer Stories

Explore success stories.

Explore success stories.

Learning on Trailhead

Events

Resources

Blogs

Become a Trailblazer.

Become a Trailblazer.

Help & Documentation

Communities

Services & Plans

Account Management

Questions? We can help.

Questions? We can help.

About Salesforce

Our Values

Our Impact

Careers

Newsroom

Legal

More Salesforce Brands

Hear our story.

Hear our story.

Events

Original Series

My List

Explore Salesforce+.

Explore Salesforce+.

Login

Products

Experiences

Contact Us

By phone

Online

Products

Experiences

Developer Centers

Salesforce Platform

Industries

Resources

Developer Tools

Build Skills

Extend Salesforce

Stay Up To Date

Community

Metadata API Developer Guide