Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

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.

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

1<?xml version="1.0" encoding="UTF-8"?>
2<OauthTokenExchangeHandler xmlns="http://soap.sforce.com/2006/04/metadata">
3    <developerName>MyTokenExchangeHandler</developerName>
4    <description>My token exchange handler</description>
5    <isAccessTokenSupported>true</isAccessTokenSupported>
6    <isEnabled>true</isEnabled>
7    <isIdTokenSupported>false</isIdTokenSupported>
8    <isJwtSupported>true</isJwtSupported>
9    <isProtected>false</isProtected>
10    <isRefreshTokenSupported>false</isRefreshTokenSupported>
11    <isSaml2Supported>false</isSaml2Supported>
12    <isUserCreationAllowed>true</isUserCreationAllowed>
13    <masterLabel>MyTokenExchangeHandler</masterLabel>
14    <tokenHandlerApex>MyOauthTokenExchangeHandler</tokenHandlerApex>
15    <enablements>
16        <apexExecutionUser>integrationuser@mycompany.com</apexExecutionUser>
17        <connectedApp>TokenExchangeApp1</conectedApp>
18        <isDefault>true</isDefault>
19    </enablements>
20</OauthTokenExchangeHandler>

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

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>*</members>
5        <name>OauthTokenExchangeHandler</name>
6    </types>
7    <version>60.0</version>
8</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.

Metadata API Developer Guide