--- schema_version: "1" id: 6e135cfb5604fc5acf83a2145871164862beccd215b52c0dde26650549f2280f title: OauthTokenExchangeHandler collection: legacydeveloper version: current locale: en-us portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/api_meta/meta_oauthtokenexchangehandler.md canonical_url: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_oauthtokenexchangehandler.htm source_site: developer.salesforce.com content_type: documentation content_hash: e020888607a91942193268fc25f65354da225cf677097953afda59374eb0a554 description: Represents a token exchange handler. The token exchange handler also consists of an Apex class. During the OAuth 2.0 token exchange flow, the token exchange handler is used to validate tokens from an external identity provider and to map users to Salesforce. --- # OauthTokenExchangeHandler Represents a token exchange handler. The token exchange handler also consists of an Apex class. During the OAuth 2.0 token exchange flow, the token exchange handler is used to validate tokens from an external identity provider and to map users to Salesforce. ![Important](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note_important.png) #### Important 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. ## Parent Type This type extends the [Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm "The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.") 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\[\]](#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. | | isContactCreationAllowed | Field Type boolean Description For internal use only. | | 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](https://developer.salesforce.com/docs/atlas.en-us.pkg1_dev.meta/pkg1_dev/packaging_protected_components.htm). | | 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. MyTokenExchangeHandler My token exchange handler true true false true false false false true MyTokenExchangeHandler MyOauthTokenExchangeHandler integrationuser@mycompany.com TokenExchangeApp1 true The following is an example package.xml that references the previous definition. \* OauthTokenExchangeHandler 60.0 ## 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](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based_zip_file.htm "The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest (package.xml) that lists what to retrieve or deploy, and one or more XML components that are organized into folders.").