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.

This type extends Metadata and inherits its fields.

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

Introduced in API version 60.0.

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

• Type: string
• Required: Yes
• Description: Required. A description for your token exchange handler.

• Type: string
• Required: Yes
• Description: Required. The API name for the handler.

• Type: OauthTokenExchHandlerApp[]
• Required: No
• 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.

• Type: boolean
• Required: Yes
• 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.

• Type: boolean
• Required: Yes
• Description: For internal use only.

• Type: boolean
• Required: Yes
• Description: Required. Indicates whether the handler is enabled. To complete enablement, add an enablements field that specifies the enablement settings.

• Type: boolean
• Required: Yes
• Description: Required. Indicates whether the handler supports OpenID Connect ID tokens from the identity provider.

• Type: boolean
• Required: Yes
• Description: Required. Indicates whether the handler supports tokens from the identity provider that are in JWT format, such as JWT-based access tokens.

• Type: boolean
• Required: No
• Description: Indicates whether the handler can be linked to or referenced by components created in a subscriber org. See Protected Components in Managed Packages.

• Type: boolean
• Required: Yes
• Description: Required. Indicates whether the handler supports OAuth 2.0 refresh tokens from the identity provider.

• Type: boolean
• Required: Yes
• Description: Required. Indicates whether the handler supports SAML 2.0 assertions from the identity provider.

• Type: boolean
• Required: Yes
• 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.

• Type: string
• Required: Yes
• Description: Required. The label of the token exchange handler record.

• Type: string
• Required: Yes
• 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.

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.

• Type: string
• Required: Yes
• Description: Required. A user who runs the Apex token exchange handler. We recommend that you use an integration user.

• Type: string
• Required: No
• Description: The API name of the connected app that’s being used to integrate with Salesforce.

• Type: string
• Required: No
• Description: The API name of the external client app that’s being used to integrate with Salesforce.

• Type: boolean
• Required: Yes
• 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.

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>

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.