Metadata API Developer’s Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

ConnectedApp

Represents a Connected App application. A connected app is an application that integrates with salesforce.com 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 applications. It 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.com should use for contacting you or your support team.
contactPhone string The phone number for salesforce.com 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.
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.
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.
  • 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.
  • None—The canvas app can appear only in the Canvas App Previewer.
  • OpenCTI—The canvas app can appear in the call control tool.
  • Publisher—The canvas app can appear as a global publisher 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) If you use Force.com Canvas, this field indicates if you want to hide the share button and header in the publisher for your canvas app. Valid values are:
  • HideShare—The Share button is hidden in the publisher for the related canvas app.
  • HideHeader—The header is hidden in the publisher for the related canvas app.

Available in API version 30.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
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.
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.
  • 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).
  • 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.
  • 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 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.
  • 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, click Manage Apps | 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>