ConnectedApp | Metadata API Developer Guide

Represents a connected app configuration. A connected app integrates an application with Salesforce using APIs. Connected apps use standard SAML and OAuth protocols to authenticate, provide Single Sign-On, and provide tokens for use with Salesforce APIs. In addition to standard OAuth capabilities, connected apps allow administrators to set various security policies and have explicit control over who may use the corresponding applications. 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	ConnectedAppAttribute	A custom attribute of the connected app.
canvasConfig	ConnectedAppCanvasConfig	The configuration options of the connected app if it’s exposed as a canvas app.
contactEmail	string	The email address Salesforce should use for contacting you or your support team.
contactPhone	string	The phone number for Salesforce to use in case we need to contact you.
description	string	An optional description for your application.
iconUrl	string	Reserved for future use.
infoUrl	string	An optional URL for a Web page with more information about your application.
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	The name of the app.
logoUrl	string	An optional application logo. The logo appears with the application’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 application’s default start page after authentication completes. If the connected app that you’re creating is a canvas app, then you don’t need to enter a value for this field. The Canvas App URL field contains the URL that gets called for the connected app.
oauthConfig	ConnectedAppOauthConfig	Specifies how your application communicates with Salesforce.
plugin	string	The name of a custom Apex class that extends `Auth.ConnectedAppPlugin` to customize the behavior of the app.
samlConfig	ConnectedAppSamlConfig	Controls how the app uses single sign-on.
startUrl	string	If the app is not 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 application’s default start page after authentication completes. 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 don’t need to enter a value for this field. 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. These values should be tailored to a specific service provider.

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

ConnectedAppCanvasConfig

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)	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 won’t be 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	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. This field is 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 Salesforce1 app. This value is 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 Salesforce1 app, the canvas app appears in the record detail page. This value is 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 you want 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`—The app can be installed by end users 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. This field is available in API version 31.0 and later.

ConnectedAppIpRange

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

Field Name	Field Type	Description
description	string	Use this field to identify the purpose of the range, such as which part of a network corresponds to this range. This field is available in API version 31.0 and later.
startAddress	string	The first address in the IP range, inclusive.
endAddress	string	The last address in the IP range, inclusive.

ConnectedAppOauthConfig

Represents the field names that make up a custom attribute in a ConnectedApp.

Field Name	Field Type	Description
callbackUrl	string	The endpoint that Salesforce calls back to your application 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, this field write-enabled. Once set, the value cannot be edited. The value must be alphanumeric (no special characters and no spaces) and a minimum of eight characters (maximum of 256 characters). If you specify a key already in use for another connected app in the organization, you’ll get an error.
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, this value is generated by Salesforce when you create the connected app. However, the field is write-enabled so you can customize the shared secret value. Once set, the value is not returned in metadata API requests. The value must be alphanumeric (no special characters and no spaces) and a minimum of eight characters (maximum of 256 characters). If you specify a secret already in use for another connected app in the organization, you’ll get an error. This field is available in API version 32.0 and later.
scopes	ConnectedAppOauthAccessScope (enumeration of type string)	The scopes refer to permissions given by the user running the connected app. When deploying metadata, valid values are: `Address`—Allows access to the logged-in user’s street address (the same behavior as deploying `Basic`). `Api`—Allows access to the logged-in user’s account over the APIs. `Basic`—Allows access to your identity URL service (the same behavior as deploying `Address`, `Email`, `Phone`, and `Profile`). `Chatter`—Allows access to only the Chatter REST API resources. `CustomApplications`—Provides access to custom applications, such as those using Visualforce. `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. `Email`—Allows access to the logged-in user’s email address (the same behavior as deploying `Basic`). `Full`—Allows access to all data accessible by the logged-in user. `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`). `OpenID`—Allows access to the logged-in user’s unique identifier for OpenID Connect apps. `Phone`—Allows access to the logged-in user’s phone number value (the same behavior as deploying `Basic`). `Profile`—Allows access to the logged-in user’s profile (the same behavior as deploying `Basic`). `RefreshToken`—Allows a refresh token to be returned if you’re eligible to receive one (the same behavior as deploying `OfflineAccess`). `Wave`—Allows access to the Wave REST API resources. Available in API version 35.0 and later. `Web`—Allows the ability to use the `access_token` on the Web. This also includes `visualforce`, allowing access to Visualforce pages. 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 Chatter 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. `RefreshToken`—Allows a refresh token to be returned if you are eligible to receive one, and is synonymous with allowing `OfflineAccess`. `Wave`—Allows access to the Wave REST API resources. Available in API version 35.0 and later. `Web`—Allows the ability to use the `access_token` on the Web. This also includes `visualforce`, allowing access to Visualforce pages.

ConnectedAppSamlConfig

Specifies how an app uses single sign-on.

Field Name	Field Type	Description
acsUrl	string	The assertion consumer service URL from the service provider.
certificate	string	The PEM-encoded certificate string, if the app uses a certificate.
entityUrl	string	The entity ID from your service provider.
encryptionCertificate	string	This page is about Classic Encryption, not Shield Platform Encryption. Note 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)	This page is about Classic Encryption, not Shield Platform Encryption. Note 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. `Triple_Des`—Triple Data Encryption Algorithm. Available in API version 30.0 and later.
issuer	string	A URI that sends the SAML response. It can be used by the service provider to determine which identity provider sent the response. Available in API version 29.0 and later.
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`—No format given. This is the default. `EmailAddress`—Used if the subject type is the user’s name ora 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.
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)	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 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`.

Declarative Metadata Sample Definition

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>

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  <fullName>AConnectedApp</fullName>
4  <attributes>
5    <formula>$User.CompanyName</formula>
6    <key>companyName</key>
7  </attributes>
8  <contactEmail>joe@company.com</contactEmail>
9  <mobileStartUrl>https://m.connectedapp.company.com</mobileStartUrl>
10  <label>A ConnectedApp</label>
11  <oauthConfig>
12    <callbackUrl>https://callback.company.com</callbackUrl>
13    <scopes>Basic</scopes>
14    <scopes>Chatter</scopes>
15  </oauthConfig>
16  <samlConfig>
17    <acsUrl>http://acs.company.com</acsUrl>
18    <entityUrl>http://samlentityId.company.com</entityUrl>
19    <samlSubjectType>Username</samlSubjectType>
20  </samlConfig>
21  <startUrl>https://connectedapp.company.com</startUrl>
22  <ipRanges>
23    <endAddress>10.0.0.46</endAddress>
24    <startAddress>10.0.0.42</startAddress>
25  </ipRanges>
26  <ipRanges>
27    <endAddress>10.0.0.32</endAddress>
28    <startAddress>10.0.0.25</startAddress>
29  </ipRanges>
30</ConnectedApp>

Usage

If you're constructing a SAML-enabled connected app using Metadata API, and need to 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>