ConnectedApp | Metadata API Developer Guide

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

File Suffix and Directory Location

ConnectedApp components have the suffix .connectedApp and are stored in the connectedApps folder.

Version

ConnectedApp components are available in API version 29.0 and later.

Fields

Field Name	Field Type	Description
attributes	canvasConfig	A custom attribute of the connected app.
	AppCanvasConfig	The configuration options of the connected app if it's exposed as a canvas app.
contactEmail	string	Required. The email address that Salesforce uses to contact you or your support team.
contactPhone	string	The phone number for Salesforce to use to contact you.
description	string	An optional description for your app.
iconUrl	string	Reserved for future use.
infoUrl	string	An optional URL for a web page with more information about your app.
ipRanges	ConnectedAppIpRange[]	Specifies the ranges of IP addresses that can access the app without requiring the user to authenticate with the connected app.
label	string	Required. The name of the app.
logoUrl	string	An optional logo for the app. The logo appears with the app’s entry in the list of apps and on the consent page the user sees when authenticating. The URL must use HTTPS, and the logo can't be larger than 125 pixels high or 200 pixels wide. The default logo is a cloud.
mobileStartUrl	string	Users are directed to this URL after they've authenticated when the app is accessed from a mobile device. If you don't give a URL, the user is sent to the app’s default start page after authentication completes. If the connected app that you’re creating is a canvas app, then you can leave this field blank. The Canvas App URL field contains the URL that gets called for the connected app.
oauthConfig	connectedAppOauthConfig	Specifies how your app communicates with Salesforce.
oauthPolicy	ConnectedAppOauthPolicy	Specifies Oauth access policies associated with your connected app. Available in API version 49.0 and later.
permissionSetName	string[]	Specifies the permissions required to perform different functions with the connected app. Available in API version 46.0 and later. You can assign multiple permission sets to the connected app, but you must enter each permission set name on a separate line. You can’t enter the same permission set name more than one time for each connected app. You can also change a permission set by replacing the current permission set with a new permission set. Make sure that each permission set name assigned to the connected app is unique. You can delete individual permission sets or remove all permission sets from a connected app by entering an empty permissionSetName string on deployment of the connected app: (`<permissionSetName></permissionSetName>`). To use this field, the isAdminApproved field on the ConnectedAppOauthConfig subtype must be set to `true`.
plugin	string	The name of a custom Apex class that extends `Auth.ConnectedAppPlugin` to customize the behavior of the app.
pluginExecutionUser	string	Specifies the user to run the plugin as. If the user isn’t authorized to use the connected app, use the `authorize` method. See the ConnectedAppPlugin class in the Apex Developer Guide. Available in API version 46.0 and later. Enter a user that is part of your org. Otherwise, the user is removed from this field when you deploy the connected app. If you don’t want to specify a user, you can leave this field empty. To use this field in an org, the ConAppPluginExecuteAsUser setting must be enabled.
profileName	string[]	Specifies the profile (base-level user permissions) required to perform different functions with the connected app. Available in API version 46.0 and later. You can assign multiple profiles to the connected app, but you must enter each profile name on a separate line. You can’t enter the same profile name more than one time for each connected app. You can also change profiles by replacing the current profiles with new profiles. Make sure that each profile name assigned to the connected app is unique. You can also delete individual profiles or remove all profiles from a connected app by entering an empty profileName string on deployment of the connected app: (`<profileName></profileName>`). To use this field, the isAdminApproved field on the ConnectedAppOauthConfig subtype must be set to `true`.
samlConfig	ConnectedAppSamlConfig	Controls how the app uses single sign-on.
sessionPolicy	ConnectedAppSessionPolicy	Specifies a connected app’s session policies. Available in API version 49.0 and later.
startUrl	string	If the app isn’t accessed from a mobile device, users are directed to this URL after they've authenticated. If you don't give a URL, the user is sent to the app’s default start page after authentication completes. Whether you give a URL or not, the start URL can be updated later by managing the connected app. If the app is accessed from a mobile device, see mobileStartUrl. If the connected app that you’re creating is a canvas app, then you can leave this field empty. The Canvas App URL field contains the URL that gets called for the connected app.

ConnectedAppAttribute

Represents the field names that make up a custom attribute when using SAML with a ConnectedApp. Tailor these values to a specific service provider.

Field Name	Field Type	Description
formula	string	Required. The value of the attribute.
key	string	Required. The attribute's identifier.

ConnectedAppCanvasConfig

Represents the configuration options of the connected app if it's exposed as a canvas app.

Field Name	Field Type	Description
accessMethod	AccessMethod (enumeration of type string)	Required. Indicates how the canvas app initiates the OAuth authentication flow. The valid values are: `Get`—OAuth authentication is used, and the user is prompted to allow the third-party application to access their information. When you use this access method, the canvas app must initiate the OAuth authentication flow. `Post`—OAuth authentication is used, but when the administrator installs the canvas app, they implicitly allow access for users. Therefore, the user isn’t prompted to allow the third party to access their user information. When you use this access method, the authentication is posted directly to the canvas app URL.
canvasUrl	string	Required. The URL of the third-party app that's exposed as a canvas app.
lifecycleClass	string	The name of the `Canvas.CanvasLifecycleHandler` Apex class, if you've implemented this class for custom parameters. Available in API version 31.0 and later.
locations	CanvasLocationOptions (enumeration of type string)[]	Indicates where the canvas app can appear to the user. The valid values are: `Aura`—Reserved for future use. `AppLauncher`—Reserved for future use. `Chatter`—The canvas app can appear in the app navigation list on the Chatter tab. `ChatterFeed`—The canvas app can appear as a Chatter feed item. `MobileNav`—The canvas app can appear in a mobile card in the Salesforce mobile app. Available in API version 31.0 and later. `None`—The canvas app can appear only in the Canvas App Previewer. `OpenCTI`—The canvas app can appear in the call control tool. `PageLayout`—The canvas app can appear on a page layout. When viewed in the Salesforce mobile app, the canvas app appears in the record detail page. Available in API version 31.0 and later. `Publisher`—The canvas app can appear as a global action. `ServiceDesk`—The canvas app can appear in the footer or sidebars of a Salesforce console. `UserProfile`—Reserved for future use. `Visualforce`—The canvas app can appear on a Visualforce page.
options	CanvasOptions (enumeration of type string)[]	Indicates whether to hide the Share button and header in the publisher for your canvas app and whether the app is a canvas personal app. Valid values are: `HideShare`—The Share button is hidden in the publisher for the related canvas app. Available in API version 30.0 and later. `HideHeader`—The header is hidden in the publisher for the related canvas app. Available in API version 30.0 and later. `PersonalEnabled`—End users can install the app as a canvas personal app. Available in API version 32.0 and later.
samlInitiationMethod	SamlInitiationMethod (enumeration of type string)	If you're using SAML single sign-on (SSO), indicates which provider initiates the SSO flow. `IdpInitiated`—Identity provider initiated. Salesforce makes the initial request to start the SSO flow. `SpInitiated`—Service provider initiated. The canvas app starts the SSO flow after it's invoked. `None`—The canvas app isn't using SAML SSO. Available in API version 31.0 and later.

ConnectedAppIpRange

Represents the list of IP addresses that can access the app without requiring the user to authenticate.

Field Name	Field Type	Description
description	string	Identifies the purpose of the range, such as which part of a network corresponds to this range. Available in API version 31.0 and later.
end	string	Required. The last address in the IP range, inclusive.
start	string	Required. The first address in the IP range, inclusive.

ConnectedAppOauthConfig

Represents the field names that configure how your connected app communicates with Salesforce.

Field Name	Field Type	Description
assetTokenConfig	connectedAppOauthAssetToken	The OAuth asset token configuration for the connected app OAuth settings. Available in API version 49.0 and later.
callbackUrl	string	Required. The endpoint that Salesforce calls back to your connected app during OAuth. It’s the OAuth `redirect_uri`.
certificate	string	The PEM-encoded certificate string, if the app uses a certificate.
consumerKey	string	A value used by the consumer for identification to Salesforce. Referred to as `client_id` in OAuth 2.0. In API version 32.0 and later, you can set this field’s value only during creation. After you define and save the value, it can’t be edited. The value must be alphanumeric, can’t contain special characters or spaces, and must be between 8–256 characters. Consumer keys must be globally unique.
consumerSecret	string	A value that is combined with the consumerKey and used by the consumer for identification to Salesforce. Referred to as `client_secret` in OAuth 2.0. Typically, Salesforce generates this value when you create the connected app. However, you can customize the shared secret value during creation. After you save the value, it can’t be edited. When set, the value isn’t returned in Metadata API requests. The value must be alphanumeric (no special characters and no spaces) and a minimum of 8 characters (maximum of 256 characters). If you specify a secret already in use for another connected app in the organization, an error occurs. Available in API version 32.0 and later.
idTokenConfig	ConnectedAppOauthIdToken	Specifies the ID token configuration for the connected app OAuth settings. Available in API version 43.0 and later.
isAdminApproved	boolean	If set to `false` (default), anyone in the org can authorize the app. Users must approve the app the first time they access it. If set to `true`, only users with the appropriate profile or permission set can access the app. These users don’t have to approve the app before they can access it. Manage profiles for the app by editing each profile’s Connected App Access list. Manage permission sets for the app by editing each permission set’s Assigned Connected App list. This setting isn’t available in Group Edition. Available in API version 46.0 and later. Connected app consumers can edit this setting when deploying a connected app in their org.
isClientCredentialEnabled	boolean	If set to `true`, the connected app can use the OAuth 2.0 client credentials flow. To use the client credentials flow, you must also specify a user for oauthClientCredentialUser. If set to `false` (default), the connected app can’t use the client credentials flow. Available in API version 56.0 and later.
isCodeCredentialEnabled	boolean	Determines whether the app can use the Authorization Code and Credentials Flow to provide identity services to headless, off-platform apps. The Authorization Code and Credentials Flow is the foundation of headless login, headless registration, headless passwordless login, and headless guest identity. If set to `true`, the connected app can use the Authorization Code and Credentials Flow and all associated Headless Identity features. The default value is `false`. This field is available in API version 57.0 and later.
isCodeCredentialPostOnly	boolean	For the Authorization Code and Credentials Flow, determines whether the user’s credentials must be sent in the body of the initial HTTPS POST request to the Salesforce authorization endpoint. Requiring the credentials in the POST body instead of in the header improves security. If set to `true`, the user’s credentials must be included in the POST body. The default value is `false`. This field is available in API version 57.0 and later.
isConsumerSecretOptional	boolean	If set to `false` (default), the connected app’s client secret is required in exchange for an access token in the OAuth 2.0 web server flow. If the client app can’t keep the client secret confidential and it must use the web server flow, set to `true`. A client secret is still generated for the connected app, but this setting instructs the web server flow not to require the `client_secret` parameter in the access token request. We recommend the user agent flow as a more secure option than web server flow without the secret. Available in API version 49.0 and later.
isIntrospectAllTokens	boolean	If set to `true`, authorizes the connected app to introspect all access and refresh tokens within the entire org. If set to `false` (default), the connected app can introspect its own tokens. In addition, an OAuth client that directly registers OAuth 2.0 connected apps through the dynamic client registration endpoint can check the tokens for itself and its registered apps. Available in API version 49.0 and later.
isNamedUserJwtEnabled	boolean	If set to `true`, the connected app is enabled to issue JSON Web Token (JWT)-based access tokens. This field is generally available in API version 59.0 and later.
isPkceRequired	boolean	Determines whether the Proof Key for Code Exchange (PKCE) extension is required for variations of the OAuth 2.0 authorization code flow configured for the connected app, including the web server flow and Authorization Code and Credentials Flow. For public client apps that can’t keep the consumer secret confidential, such as mobile apps, the PKCE extension helps ensure that the client that initiates an authorization flow is the same client that completes it. For this reason, we always recommend implementing PKCE for public clients. We also strongly recommend that you implement PKCE for private clients. If set to `true`, the PKCE extension is required and any authorization code flow variations that don’t implement it fail. If set to `false`, you can still implement PKCE but it isn’t required. The default value is `false`. This field is available in API version 59.0 and later.
isRefreshTokenRotationEnabled	boolean	If set to `true`, the connected app issues a new refresh token each time the OAuth refresh token flow is invoked. The old refresh token is automatically invalidated. If a user tries to use a previous refresh token that’s been invalidated, the current refresh token and its associated access tokens get deleted. If set to `false`, the refresh token can be used to obtain multiple access tokens. This field is available in API version 60.0 and later.
isSecretRequiredForRefreshToken	boolean	If set to `true` (default), the app’s client secret is required in the authorization request of a refresh token and hybrid refresh token flow. If set to `false` and an app sends the client secret in the authorization request, Salesforce still validates it. Select this option for web-server based apps that can protect client secrets. For apps that can’t protect client secrets, such as mobile apps or apps installed on a user’s computer, we recommend against selecting this option. Available in API version 51.0 and later.
isSecretRequiredForTokenExchange	boolean	If set to `true`, the connected app must include its consumer secret (`client_secret`) in the token request during the OAuth 2.0 token exchange flow. For security, set this field to `true` only if your app has a private client backend where it can keep the secret safe. For public client apps, such as single-page apps and mobile apps, set this field to `false` and don’t include the consumer secret. This field is available in API version 60.0 and later.
isTokenExchangeEnabled	boolean	If set to `true`, the connected app can use the OAuth 2.0 token exchange flow to exchange tokens from an external identity provider for Salesforce tokens. This field is available in API version 60.0 and later.
oauthClientCredentialUser	string	The execution user for the OAuth 2.0 client credentials flow. Salesforce returns access tokens on behalf of this user. This user must have the API Only permission. To use this field, set isClientCredentialEnabled to `true` and specify a consumerKey. Available in API version 56.0 and later.
scopes	ConnectedAppOauthAccessScope (enumeration of type string)[]	The permissions given by the user running the connected app. When deploying metadata, valid values are: `Basic`—Allows access to your identity URL service (the same behavior as deploying `Address`, `Email`, `Phone`, and `Profile`). `Api`—Allows access to the logged-in user's account over the APIs. `Web`—Allows use of the `access_token` on the web. This usage also includes `visualforce`, allowing access to Visualforce pages. `Full`—Allows access to all data accessible by the logged-in user. `Chatter`—Allows access to only the Connect REST API resources. `CustomApplications`—Provides access to custom applications, such as those using Visualforce. `RefreshToken`—Allows a refresh token to be returned if you’re eligible to receive one (the same behavior as deploying `OfflineAccess`). `OpenID`—Allows access to the logged-in user's unique identifier for OpenID Connect apps. `Profile`—Allows access to the logged-in user's profile (the same behavior as deploying `Basic`). `Email`—Allows access to the logged-in user's email address (the same behavior as deploying `Basic`). `Address`—Allows access to the logged-in user's street address (the same behavior as deploying `Basic`). `Phone`—Allows access to the logged-in user's phone number value (the same behavior as deploying `Basic`). `OfflineAccess`—Allows the app to interact with the user's data while the user is offline and get a refresh token (the same behavior as deploying `RefreshToken`). `CustomPermissions`—Allows access to the custom permissions in an organization associated with the connected app and shows whether the current user has each permission enabled. `Wave`—Allows access to the Analytics REST API resources. Available in API version 35.0 and later. `Eclair`—Allows access to the Analytics REST API Charts Geodata resource. Available in API version 35.0 and later. `Pardot`—Allows access to Pardot API services on behalf of the user. The full extent of accessible services is managed by the Pardot account. Available in API version 49.0 and later. `Lightning`—Allows hybrid apps to directly obtain Lightning child sessions through the OAuth 2.0 hybrid app token flow and hybrid app refresh token flow. Available in API version 51.0 and later. `Content`—Allows hybrid apps to directly obtain content child sessions through the OAuth 2.0 hybrid app token flow and hybrid app refresh token flow. Available in API version 51.0 and later. `CDPIngest`—Allows access to Data Cloud ingest API services. Customers use these API services to upload and maintain external datasets in the Data 360. Available in API version 52.0 and later. `Chatbot`—Allows access to Einstein Bot API services. Available in API version 54.0 and later. `ForgotPassword`—Allows access to Headless Forgot Password API. Assign to an internal integration user to get an access token for authenticated requests to this API. Available in API version 57.0 and later. `UserRegistration`—Allows access to Headless Registration API. Assign to an internal integration user to get an access token for authenticated requests to this API. Available in API version 58.0 and later. `PwdlessLogin`—Allows access to Headless Passwordless Login API. Assign to an internal integration user to get an access token for authenticated requests to this API. Available in API version 59.0 and later. When retrieving metadata, valid values are: `Api`—Allows access to the logged-in user’s account over the APIs. `Basic`—Allows access to the user’s identity URL service, and includes `Address`, `Email`, `Phone`, and `Profile`. `Chatter`—Allows access to only the Connect REST API resources. `CustomApplications`—Allows access to custom applications, such as those using Visualforce. `Full`—Allows access to all data accessible by the logged-in user. `OpenID`—Allows access to the logged-in user's unique identifier for OpenID Connect apps. `CDPIngest`—Allows access to Data Cloud ingest API services. Customers use these API services to upload and maintain external datasets in the Data 360. Available in API version 52.0 and later. `Pardot`—Allows access to Pardot API services on behalf of the user. The full extent of accessible services is managed by the Pardot account. Available in API version 49.0 and later. `Lightning`—Allows hybrid apps to directly obtain Lightning child sessions through the OAuth 2.0 hybrid app token flow and hybrid app refresh token flow. Available in API version 51.0 and later. `Content`—Allows hybrid apps to directly obtain content child sessions through the OAuth 2.0 hybrid app token flow and hybrid app refresh token flow. Available in API version 51.0 and later. `RefreshToken`—Allows a refresh token to be returned if you’re eligible to receive one and is synonymous with allowing `OfflineAccess`. `Wave`—Allows access to the Analytics REST API resources. Available in API version 35.0 and later. `Eclair`—Allows access to the Analytics REST API Charts Geodata resource. Available in API version 35.0 and later. `Web`—Allows usage of the `access_token` on the web. This usage also includes `visualforce`, allowing access to Visualforce pages. `Chatbot`—Allows access to Einstein Bot API services. Available in API version 54.0 and later. `ForgotPassword`—Allows access to Headless Forgot Password API. Assign to an internal integration user to get an access token for authenticated requests to this API. Available in API version 57.0 and later. `UserRegistration`—Allows access to Headless Registration API. Assign to an internal integration user to get an access token for authenticated requests to this API. Available in API version 58.0 and later. `PwdlessLogin`—Allows access to Headless Passwordless Login API. Assign to an internal integration user to get an access token for authenticated requests to this API. Available in API version 59.0 and later.
singleLogoutUrl	string	The single logout endpoint. This URL is the endpoint where Salesforce sends a logout request when users log out of Salesforce.

ConnectedAppOauthAssetToken

Specifies an OAuth asset token configuration for the connected app OAuth settings. Available in API version 49.0 and later.

Field Name	Field Type	Description
assetAudiences	string	Required. The audience claim associated with the asset token payload. This claim identifies who the JWT is intended for. Value is an array of case-sensitive strings, each containing a `StringOrURI` value. An audience is specified for each intended consumer of the asset token.
assetIncludeAttributes	boolean	Required. If set to `true` (default), custom attributes associated with the connected app are included in the asset token payload. If set to `false`, these attributes aren’t included.
assetIncludeCustomPerms	boolean	Required. If set to `true` (default), custom permissions associated with the connected app are included in the asset token payload. If set to `false`, these permissions aren’t included.
assetSigningCertId	string	Required. The ID of the JWT certificate’s signing secret. The certificate size can’t exceed 4 KB. If it does, try using a DER encoded file to reduce the size.
assetValidityPeriod	int	Required. The asset token’s validity period. The validity must be the expiration time of the assertion within 3 minutes, expressed as the number of seconds from 1970-01-01T0:0:0Z measured in UTC.

ConnectedAppOauthIdToken

Specifies the ID token configuration for the connected app OAuth settings. Available in API version 43.0 and later.

Field Name	Field Type	Description
idTokenAudience	string	The audiences that this ID token is intended for. The value is an array of case-sensitive strings. If no audiences are specified, the OAuth 2.0 `client_id` of the relying party is returned as the default audience. Otherwise, the other audiences are returned with the `client_id` in the `aud` value.
idTokenIncludeAttributes	boolean	Indicates whether attributes are included in the ID token.
idTokenIncludeCustomPerms	boolean	Indicates whether custom permissions are included in the ID token.
idTokenIncludeStandardClaims	boolean	Indicates whether standard claims about the authentication event are included in the ID token.
idTokenValidity	int	The length of time that the ID token is valid for after it’s issued. The value can be from 1 to 720 minutes. The default is 2 minutes.

ConnectedAppOauthPolicy

Specifies OAuth access policies for the connected app. Available in API version 49.0 and later.

Field Name	Field Type	Description
ipRelaxation	string	Required. Specifies whether a user’s access to the connected app is restricted by IP ranges. Valid options are: `ENFORCE` (default)—Enforces the IP restrictions configured for the org, such as the IP ranges assigned to a user profile. `BYPASS_2FACTOR`—Allows a user running the app to bypass the org’s IP restrictions when either of these conditions is true. The app has a list of allowed IP ranges and is using the web server OAuth authorization flow. Requests coming from only these IPs are allowed. The app doesn’t have a list of allowed IP ranges, but it uses the web server authentication flow. And the user successfully completes identity verification if accessing Salesforce from a new browser or device. `BYPASS`—Allows a user to run this app without org IP restrictions. `ENFORCE_RELAXREFRESH`—Enforces the IP restrictions configured for the org, such as the IP ranges assigned to a user profile. However, this option bypasses these restrictions when the connected app uses refresh tokens to get access tokens.
refreshTokenPolicy	string	Required. Specifies how long a refresh token is valid for. If refresh tokens are provided, users can continue to access the OAuth-enabled connected app without having to reauthorize when the access token expires, as defined by the session timeout value. The connected app exchanges the refresh token with an access token to start a new session. The Refresh Token policy is evaluated only during usage of the issued refresh token and doesn’t affect a user’s current session. Refresh tokens are required only when a user’s session has expired or isn’t available. For example, you set a refresh token policy to expire the token after 1 hour. If a user uses the app for 2 hours, the user isn’t forced to reauthenticate after 1 hour. However, the user is required to authenticate again when the session expires and the client attempts to exchange its refresh token for a new session. Valid options are: `zero`—The refresh token is invalid immediately. The user can use the current session (access token) already issued, but can’t obtain a new session when the access token expires. `infinite`—The refresh token is used indefinitely, unless revoked by the user or Salesforce admin. Default setting. `specific_lifetime:number:HOURS, DAYS, MONTHS`—The refresh token is valid for a fixed amount of time. For example, if the policy states `specific_lifetime:1:DAYS`, the user can obtain new sessions for only 24 hours. `specific_inactivity:number:HOURS, DAYS, MONTHS`—The refresh token is valid as long as it’s been used within the specified amount of time. For example, if set to `specific_inactivity:7:DAYS`, and the refresh token isn’t exchanged for a new session within seven days, the next attempt to use the token fails. The expired token can’t generate new sessions. If the refresh token is exchanged within seven days, the token is valid for another seven days. The monitoring period of inactivity also resets.
singleLogoutUrl	string	If single logout is enabled, specify the single logout URL. Salesforce sends logout requests to this URL when users log out of Salesforce. The single logout URL must be an absolute URL starting with `https://`.

Field Name

Field Type

Description

ipRelaxation

string

Required. Specifies whether a user’s access to the connected app is restricted by IP ranges. Valid options are:

ENFORCE (default)—Enforces the IP restrictions configured for the org, such as the IP ranges assigned to a user profile.
BYPASS_2FACTOR—Allows a user running the app to bypass the org’s IP restrictions when either of these conditions is true.
- The app has a list of allowed IP ranges and is using the web server OAuth authorization flow. Requests coming from only these IPs are allowed.
- The app doesn’t have a list of allowed IP ranges, but it uses the web server authentication flow. And the user successfully completes identity verification if accessing Salesforce from a new browser or device.
BYPASS—Allows a user to run this app without org IP restrictions.
ENFORCE_RELAXREFRESH—Enforces the IP restrictions configured for the org, such as the IP ranges assigned to a user profile. However, this option bypasses these restrictions when the connected app uses refresh tokens to get access tokens.

refreshTokenPolicy

string

Required. Specifies how long a refresh token is valid for.

If refresh tokens are provided, users can continue to access the OAuth-enabled connected app without having to reauthorize when the access token expires, as defined by the session timeout value. The connected app exchanges the refresh token with an access token to start a new session. The Refresh Token policy is evaluated only during usage of the issued refresh token and doesn’t affect a user’s current session. Refresh tokens are required only when a user’s session has expired or isn’t available. For example, you set a refresh token policy to expire the token after 1 hour. If a user uses the app for 2 hours, the user isn’t forced to reauthenticate after 1 hour. However, the user is required to authenticate again when the session expires and the client attempts to exchange its refresh token for a new session.

Valid options are:

zero—The refresh token is invalid immediately. The user can use the current session (access token) already issued, but can’t obtain a new session when the access token expires.
infinite—The refresh token is used indefinitely, unless revoked by the user or Salesforce admin. Default setting.
specific_lifetime:number:HOURS, DAYS, MONTHS—The refresh token is valid for a fixed amount of time. For example, if the policy states specific_lifetime:1:DAYS, the user can obtain new sessions for only 24 hours.
specific_inactivity:number:HOURS, DAYS, MONTHS—The refresh token is valid as long as it’s been used within the specified amount of time. For example, if set to specific_inactivity:7:DAYS, and the refresh token isn’t exchanged for a new session within seven days, the next attempt to use the token fails. The expired token can’t generate new sessions. If the refresh token is exchanged within seven days, the token is valid for another seven days. The monitoring period of inactivity also resets.

singleLogoutUrl

string

If single logout is enabled, specify the single logout URL. Salesforce sends logout requests to this URL when users log out of Salesforce. The single logout URL must be an absolute URL starting with https://.

ConnectedAppSamlConfig

Specifies how an app uses single sign-on.

Field Name	Field Type	Description
acsUrl	string	Required. The assertion consumer service URL from the service provider.
certificate	string	The PEM-encoded certificate string, if the app uses a certificate.
encryptionCertificate	string	The name of the certificate to use for encrypting SAML assertions to the service provider. This certificate is saved in the organization's Certificate and Key Management list. Available in API version 30.0 and later.
encryptionType	SamlEncryptionType (enumeration of type string)	When Salesforce is the identity provider, the SAML configuration can specify the encryption method used for encrypting SAML assertions to the service provider. The service provider detects the encryption method in the SAML assertion for decryption. Valid values are: `AES_128`—128–bit key `AES_256`—256–bit key Available in API version 30.0 and later.
entityUrl	string	Required. The entity ID from your service provider.
issuer	string	A URI that sends the SAML response. A service provider can use this URI to determine which identity provider sent the response. Available in API version 29.0 and later.
samlIdpSLOBindingEnum	SamlIdpSLOBinding (enumeration of type string)	The SAML HTTP binding type from the service provider used for single logout. Available in API version 40.0 and later. Valid values are: `PostBinding` `RedirectBinding`
samlNameIdFormat	SamlNameIdFormatType (enumeration of type string)	Indicates the format the service provider (SP) requires for the user's single sign-on identifier. Available in API version 29.0 and later. Valid values are: `Unspecified` (default)—No format given. `EmailAddress`—Used if the subject type is the user's name or a federation ID (an ID internal to the SP). `Persistent`—Used with the user ID and persistent ID subject types. `Transient`—Used when the subject type is a custom attribute and can change every time the user logs in.
samlSigningAlgoType	SamlSigningAlgoType (enumeration of type string)	Indicates the signing algorithm applied to SAML requests and responses when Salesforce is the identity provider. The selected signing algorithm is applied to both single sign-on and single logout responses from your org. Available in API version 50.0 and later. Valid values are: `SHA1` `SHA256`
samlSloUrl	string	The SAML single-logout endpoint of the connected app service provider (SP). This endpoint is where SAML LogoutRequests and LogoutResponses are sent when users log out of Salesforce. The SP provides this endpoint. Available in API version 40.0 and later.
samlSubjectCustomAttr	string	If the samlSubjectType is `CustomAttr`, include that custom value here; otherwise, leave empty. Available in API version 29.0 and later.
samlSubjectType	SamlSubjectType (enumeration of type string)	Required. The single sign-on identifier for the user. Valid values are: `Username`—The user's Salesforce name. `FederationId`—The user's identifier at the service provider. Get this value from the service provider. `UserId`—The user's 15-character Salesforce identifier. `PersistentID`—A persistent opaque identifier that is specific to the identity provider and a service provider. `CustomAttr`—The identifier is taken from a custom field value in samlSubjectCustomAttr.

ConnectedAppSessionPolicy

Specifies the configuration options for a connected app’s session policies. Use these policies to define how long a user’s session can last before reauthenticating, to block user access to the connected app, or to require multi-factor authentication (MFA) to access the app. Available in API version 49.0 and later.

Field Name	Field Type	Description
policyAction	string	If the High Assurance session security level is applied to the connected app, specify associated high assurance action. Valid values are: `Block`—Makes the connected app inaccessible to your org’s users. Blocking an app ends all current user sessions with the connected app and prevents all new sessions. `RaiseSessionLevel`—Requires users to verify their identity with multi-factor authentication when they log in to the connected app. This setting applies to authorization flows that include a user approval step for API logins. These flows are the OAuth 2.0 refresh token flow, web server flow, and user-agent flow. All other flows, such as the JSON Web Token (JWT) bearer token flow, don’t include a user approval step. For flows without a user approval step, API logins with the High Assurance session security level are blocked.
sessionLevel	string	Applies the High Assurance session security level to the connected app. This session level requires users to verify their identity with multi-factor authentication when they log in to the connected app.
sessionTimeout	int	The length of time the connected app’s session lasts. If you don’t set a value, Salesforce uses the timeout value in the connected app user’s profile. If the user’s profile doesn’t specify a timeout value, Salesforce uses the timeout value in the org’s Session Settings.

Declarative Metadata Sample Definition

The following is an example of a ConnectedApp component.

1<?xml version="1.0" encoding="UTF-8"?>
2<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
3    <attributes>
4        <formula>$Api.Enterprise_Server_URL_100</formula>
5        <key>test</key>
6    </attributes>
7    <attributes>
8        <formula>$Api.Partner_Server_URL_60</formula>
9        <key>test1</key>
10    </attributes>
11   <canvasConfig>
12        <accessMethod>Get</accessMethod>
13        <canvasUrl>https://salesforce.com</canvasUrl>
14        <lifecycleClass>MyCanvasListener</lifecycleClass>
15        <locations>Chatter</locations>
16        <locations>Visualforce</locations>
17        <locations>Aura</locations>
18        <locations>Publisher</locations>
19        <locations>ChatterFeed</locations>
20        <locations>OpenCTI</locations>
21        <locations>MobileNav</locations>
22        <locations>PageLayout</locations>
23        <options>HideShare</options>
24        <options>HideHeader</options>
25        <options>PersonalEnabled</options>
26        <samlInitiationMethod>None</samlInitiationMethod>
27    </canvasConfig>
28    <canvas>
29    	<locationOptions>NONE</locationOptions>
30    	<samlInitiationMethod>None</samlInitiationMethod>
31    	<accessMethod>Get</accessMethod>
32    	<canvasOptions>PE</canvasOptions>
33    	<lifecycleClass>MyCanvasListener</lifecycleClass>
34    	<canvasUrl>https://salesforce.com</canvasUrl>
35	</canvas>
36    <contactEmail>example@salesforce.com</contactEmail>
37    <contactPhone>1231231234</contactPhone>
38    <description>Test App</description>
39    <iconUrl>https://c1.sfdcstatic.com/content/dam/sfdc-docs/www/logos/salesforce-logo-cloud.png</iconUrl>
40    <infoUrl>https://c1.sfdcstatic.com/content/dam/sfdc-docs/www/logos/salesforce-logo-cloud.png</infoUrl>
41    <startUrl>https://www.salesforce.com</startUrl>
42    <ipRanges>
43        <end>000.0.0.1</end>
44        <start>000.0.0.2</start>
45	<description>Test</description>
46    </ipRanges>
47    <ipRanges>
48        <end>000.0.0.1</end>
49        <start>000.0.0.2</start>
50	<description>Test1</description>
51    </ipRanges>
52    <label>TestApp</label>
53    <logoUrl>https://c1.sfdcstatic.com/content/dam/sfdc-docs/www/logos/salesforce-logo-cloud.png</logoUrl>
54    <profileName>Test</profileName>
55    <permissionSetName>TestPermission</permissionSetName>
56    <mobileStartUrl>http://www.mobile.com</mobileStartUrl>
57    <mobileAppConfig>
58        <applicationBinaryFile></applicationBinaryFile>
59        <applicationBinaryFileName>test</applicationBinaryFileName>
60        <applicationBundleIdentifier>testtest</applicationBundleIdentifier>
61        <applicationIconFileName>test</applicationIconFileName>
62	<applicationIconFile>test</applicationIconFile>
63	<applicationFileLength>5</applicationFileLength>
64        <applicationInstallUrl>https://salesforce.com</applicationInstallUrl>
65        <devicePlatform>ios</devicePlatform>
66        <deviceType>minitablet</deviceType>
67        <minimumOsVersion>2</minimumOsVersion>
68        <privateApp>true</privateApp>
69        <version>2</version>
70    </mobileAppConfig>
71    <oauthConfig>
72        <assetTokenConfig>
73            <assetAudiences>http://asset.audience.com</assetAudiences>
74            <assetIncludeAttributes>true</assetIncludeAttributes>
75            <assetIncludeCustomPerms>true</assetIncludeCustomPerms>
76            <assetSigningCertId>${cert.id}</assetSigningCertId>
77            <assetValidityPeriod>1440</assetValidityPeriod>
78        </assetTokenConfig>
79        <callbackUrl>https://www.callback.com</callbackUrl>
80        <!--  NOTE, TEST.orgId will get replaced with the org ID of the context org, so we will have a unique consumer key in every scratch org.  -->
81        <consumerKey>3MVG9AOp4kbriZOcnmoLmTrguy9ryzcLbBjoNY...${TEST.orgId}</consumerKey>
82		<consumerSecret>3MVG9AOp4k...</consumerSecret>
83		<certificate>3MVG9AOp4kbriZOInmoLmTrguy9ryzcLbBjoNY...</certificate>
84        <scopes>Basic</scopes>
85        <scopes>Chatter</scopes>
86        <scopes>OpenID</scopes>
87        <scopes>CustomPermissions</scopes>
88		<singleLogoutUrl>https://www.logout.com</singleLogoutUrl>
89        <isAdminApproved>false</isAdminApproved>
90        <isConsumerSecretOptional>false</isConsumerSecretOptional>
91        <isIntrospectAllTokens>false</isIntrospectAllTokens>
92		<idTokenConfig>
93			<idTokenAudience>https://idtoken.audience.com</idTokenAudience>
94			<idTokenIncludeAttributes>true</idTokenIncludeAttributes>
95			<idTokenIncludeCustomPerms>true</idTokenIncludeCustomPerms>
96			<idTokenIncludeStandardClaims>true</idTokenIncludeStandardClaims>
97			<idTokenValidity>20</idTokenValidity>
98		</idTokenConfig>
99    </oauthConfig>
100    <oauthPolicy>
101        <ipRelaxation>ENFORCE</ipRelaxation>
102        <refreshTokenPolicy>infinite</refreshTokenPolicy>
103        <singleLogoutUrl>https://www.logout.com</singleLogoutUrl>
104    </oauthPolicy>
105    <plugin>ConnectedAppPluginTest</plugin>
106    <pluginExecutionUser>testuser@salesforce.com</pluginExecutionUser>
107    <samlConfig>
108        <acsUrl>http://www.acs.com</acsUrl>
109        <encryptionType>AES_128</encryptionType>
110	<encryptionCertificate>3MVG9AOp4kbriZOInmoLmTrguy9ryzcLbBjoNY...</encryptionCertificate>
111	<certificate>3MVG9AOp4kbriZOInmoLmTrguy9ryzcLbBjoNY...</certificate>
112	<samlSubjectCustomAttr>test</samlSubjectCustomAttr>
113        <entityUrl>http://www.entity.com</entityUrl>
114        <issuer>https://salesforce.com</issuer>
115        <samlIdpSLOBindingEnum>RedirectBinding</samlIdpSLOBindingEnum>
116        <samlNameIdFormat>Unspecified</samlNameIdFormat>
117        <samlSloUrl>https://www.salesforce.com</samlSloUrl>
118        <samlSubjectType>CustomAttribute</samlSubjectType>
119    </samlConfig>
120    <sessionPolicy>
121        <policyAction>RaiseSessionLevel</policyAction>
122        <sessionLevel>HIGH_ASSURANCE</sessionLevel>
123        <sessionTimeout>720</sessionTimeout>
124    </sessionPolicy>
125</ConnectedApp>

You can enter multiple callback URL values. At run time, Salesforce validates the callback URL specified by the app by matching it with one of the values. You must separate each callback URL with line breaks. To enter a new line programmatically, use the \r line break character.

Here's an example of a ConnectedApp component with multiple callback URLs.

1<?xml version="1.0" encoding="UTF-8"?>
2<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
3 <contactEmail>example@salesforce.com</contactEmail>
4 <label>MyConnectedApp</label>
5 <oauthConfig>
6 <callbackUrl>https://example.com/callback1
7https://example.com/callback2
8https://example.com/callback3</callbackUrl>
9 <consumerKey>3MVG9AOp4kbriZOcnmoLmTrguy9ryzcLbBjoNY...</consumerKey>
10 <isAdminApproved>false</isAdminApproved>
11 <isConsumerSecretOptional>false</isConsumerSecretOptional>
12 <isIntrospectAllTokens>false</isIntrospectAllTokens>
13 <isSecretRequiredForRefreshToken>true</isSecretRequiredForRefreshToken>
14 <scopes>Full</scopes>
15 <scopes>RefreshToken</scopes>
16 </oauthConfig>
17 <oauthPolicy>
18 <ipRelaxation>ENFORCE</ipRelaxation>
19 <refreshTokenPolicy>infinite</refreshTokenPolicy>
20 </oauthPolicy>
21</ConnectedApp>

The following is an example package manifest used to deploy or retrieve the ConnectedApp metadata for an organization.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>PortalTestApp</members>
5        <name>ConnectedApp</name>
6    </types>
7    <version>29.0</version>
8</Package>

Usage

If you're constructing a SAML-enabled connected app using Metadata API, and must set the IdP-Initiated Login URL for your service provider, you have two options:

You can use the service provider app ID with the app parameter in the following format. This value is displayed in the Salesforce user interface. From Setup, enter Connected Apps in the Quick Find box, then select Connected Apps, then click the name of the connected app to see its detail page.

1https://<Salesforce_base_URL>/idp/login?app=<app_id>

Or, if you're configuring the connected app using Metadata API only, you can use the apiName parameter of the service provider app in the following format. The apiName parameter is the fullName inherited from the Metadata type.

1https://<Salesforce_base_URL>/idp/login?apiName=<fullName>

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.