When you create a connected app, you specify general information about the app and settings for OAuth, web apps, mobile apps, and canvas apps. You can also customize how the app is invoked by creating a connected app handler with the ConnectedAppPlugin Apex class.
Available in: both Salesforce Classic and Lightning Experience
Connected Apps can be created in: Group, Professional, Enterprise, Performance, Unlimited, and Developer Editions
Connected Apps can be installed in: All Editions
User Permissions Needed
To create, update, or delete:
“Customize Application” AND either
“Modify All Data” OR “Manage Connected Apps”
To update all fields except Profiles, Permission Sets, and Service Provider SAML Attributes:
To update Profiles, Permission Sets, and Service Provider SAML Attributes:
“Customize Application” AND “Modify All Data”
“Download AppExchange Packages”
To create a connected app:
From Setup, enter App in the Quick Find box, then select App Manager. (1)
Click New Connected App. (2)
Be sure to select App Manager to create a connected app, not Manage Connected Apps. (3)
The information you enter to create a connected app is divided into these parts:
You can create a connected app without specifying any authorization, canvas, or mobile settings. This kind of connected app behaves like a "bookmark" to the specified URL that appears in the user’s App Launcher and the drop-down app menu. Simply enter basic information and provide a Start URL in the Web App Settings. If the destination requires authentication, the service hosting the destination URL prompts users to provide login credentials when they navigate to it.
When you’ve finished entering the information, click Save to save your new app. You can now publish your app, make further edits, or delete it. If you’re using OAuth, saving your app gives you two new values that the app uses to communicate with Salesforce.
Consumer Key: A value used by the consumer to identify itself to Salesforce. Referred to as client_id in OAuth 2.0.
Consumer Secret: A secret used by the consumer to establish ownership of the consumer key. Referred to as client_secret in OAuth 2.0.
For your convenience, you can update some fields in a connected app and the changes apply immediately to all installed versions of the app. For example, connected app descriptions are immediately updated in each version of the connected app. The following version-independent fields bypass the packaging or installation lifecycle.
Logo Image URL
Specify basic information about your app in this section, including the app name, logo, and contact information.
Enter the connected app name. This name is displayed in the App Manager and on its App Launcher tile.
The connected app name must be unique for the connected apps in your org. You can reuse the name of a deleted connected app if the connected app was created using the Spring ’14 release or later.
Enter the API name used when referring to your app from a program. It defaults to a version of the name without spaces. Only letters, numbers, and underscores are allowed, so if the original app name contains any other characters, edit the default name.
Enter the contact email for Salesforce to use when contacting you or your support team. This address isn’t given to Salesforce admins who install the app.
Enter the contact phone for Salesforce to use in case we need to contact you. This number isn’t given to Salesforce admins who install the app.
Enter a logo image URL to display your logo on the App Launcher tile. It also appears on the consent page that users see when authenticating. The URL must use HTTPS. Use a GIF, JPG, or PNG file format and a file size that’s preferably under 20 MB, but, at most 100 KB. We resize the image to 128 pixels by 128 pixels, so be sure that you like how it looks. If you don’t supply a logo, Salesforce generates one for you using the app’s initials.
You can upload your own logo image by clicking Upload logo image. Select an image from your local file system that meets the size requirements for the logo. When your upload is successful, the URL to the logo appears in the Logo Image URL field. Otherwise, make sure that the logo meets the size requirements.
You can upload your own image by clicking Upload logo image. Select an image from your local file system. When your upload is successful, the URL to the logo appears in the Logo Image URL field.
You can also select a logo from the samples provided by Salesforce by clicking Choose one of our sample logos. The logos include ones for Salesforce apps, third-party apps, and standards bodies. Click the logo you want, and then copy and paste the URL into the Logo Image URL field.
You can use a logo hosted publicly on Salesforce servers by uploading an image as a document using the Documents tab. View the image to get the URL, and then enter the URL into the Logo Image URL field.
Enter an icon URL to display a logo on the OAuth approval page that users see when they first use your app. Use an icon that’s 16 pixels high and wide and on a white background.
You can select an icon from the samples provided by Salesforce. Click Choose one of our sample logos. Click the icon you want, and then copy and paste the displayed URL into the Icon URL field.
If there is a Web page with more information about your app, provide an info URL.
Enter a description, up to 256 characters, to display on the connected app’s App Launcher tile. If you don’t supply a description, just the name appears on the tile.
The App Launcher displays the connected app’s name, description, and logo (if provided) on an App Launcher tile. Make sure that the text is meaningful and mistake-free.
API (Enable OAuth Settings)
This section controls how your app communicates with Salesforce. Select Enable OAuth Settings to configure authentication settings.
Enter the callback URL (endpoint) that Salesforce calls back to your application during OAuth. It’s the OAuth redirect_uri. Depending on which OAuth flow you use, the URL is typically the one that a user’s browser is redirected to after successful authentication. Because this URL is used for some OAuth flows to pass an access token, the URL must use secure HTTPS or a custom URI scheme. If you enter multiple callback URLs, at run time Salesforce matches the callback URL value specified by the app with one of the values in Callback URL. It must match one of the values to pass validation.
If you’re using the JWT OAuth flow, select Use Digital Signatures. If the app uses a certificate, click Choose File and select the certificate file.
Add all supported OAuth scopes to Selected OAuth Scopes. These scopes refer to permissions given by the user running the connected app and are followed by their OAuth token name in parentheses.
Access and manage your Chatter feed (chatter_api)
Allows access to Chatter REST API resources only.
Access and manage your data (api)
Allows access to the logged-in user’s account using APIs, such as REST API and Bulk API. This value also includes chatter_api, which allows access to Chatter REST API resources.
Access your basic information (id, profile, email, address, phone)
Allows access to the Identity URL service.
Access custom permissions (custom_permissions)
Allows access to the custom permissions in an org associated with the connected app. It shows whether the current user has each permission enabled.
Allow access to your unique identifier (openid)
Allows access to the logged in user’s unique identifier for OpenID Connect apps.
Full access (full)
Allows access to all data accessible by the logged-in user, and encompasses all other scopes. full doesn’t return a refresh token. You must explicitly request the refresh_token scope to get one.
Perform requests on your behalf at any time (refresh_token, offline_access)
Allows a refresh token to be returned if you are eligible to receive one. This lets the app interact with the user’s data while the user is offline. The refresh_token scope is synonymous with offline_access.
Provide access to custom applications (visualforce)
Allows access to Visualforce pages.
Provide access to your data via the Web (web)
Allows the ability to use the access_token on the Web. This also includes visualforce, allowing access to Visualforce pages.
Control how the OAuth request handles the ID token. If the OAuth request includes the openid scope, the returned token can include the ID token.
To include the ID token in refresh token responses, select Include ID Token. It’s always included in access token responses.
With the primary ID token setting enabled, configure the secondary settings that control the ID token contents in both access and refresh token responses. Select at least one of these settings.
Include Standard Claims
Include the standard claims that contain information about the user, such as the user’s name, profile, phone_number, and address. The OpenID Connect specifications define a set of standard claims to be returned in the ID token.
Include Custom Attributes
If your app has specified custom attributes, include them in the ID token.
Include Custom Permissions
If your app has specified custom permissions, include them in the ID token.
If your org had the No user approval required for users in this organization option selected on your remote access before the Spring ’12 release, users in the same org as the one the app was created in still have automatic approval for the app. The read-only No user approval required for users in this organization option is selected to show this condition. For connected apps, the recommended procedure after you’ve created an app is for admins to install the app and then set Permitted Users to Admin-approved users. If the remote access option wasn’t originally selected, the option doesn’t display.
Web App Settings
Enter a start URL for your app to direct users to a specific location after they’ve authenticated. If you don’t enter a start URL, users are sent to the app’s default start page after authentication completes. If the connected app that you’re creating is a canvas app, you can skip this field. The Canvas App URL field contains the URL that gets called for the connected app.
If your connected app uses a SAML service provider, select Enable SAML. Enter the entity Id, ACS URL, subject type, name ID format, and issuer, available from your service provider. Select Verify Request Signatures if the service provider gave you a security certificate. Browse your system for the certificate. This is only necessary if you plan to initiate logging into Salesforce from the service provider and the service provider signs their SAML requests.
If you upload a certificate, all SAML requests must be signed. If no certificate is uploaded, all SAML requests are accepted.
Optionally, select Encrypt SAML Response to upload a certificate and select an encryption method for encrypting the assertion. Valid encryption algorithm values are AES–128 (128–bit key), AES–256 (256–bit key), and Triple-DES (Triple Data Encryption Algorithm).
Custom Connected App Handler
Customize the behavior of a connected app with Apex. Create a class that extends the ConnectedAppPlugin
Apex class, and associate it with a connected app. The class can support new authentication protocols or respond to user attributes in a way that benefits a business process.
The plug-in runs on behalf of a user account. In the Run As field, select the user for the plug-in. If the user isn’t authorized for the connected app, use the authorize method to do so. For more information, see the ConnectedAppPlugin class in the Apex Code Developer's Guide.
Mobile App Settings
Enter the mobile start URL to direct users to a specific location when the app is accessed from a mobile device. If you don’t enter a mobile start URL, users are sent to the start URL defined under Web App Settings. If the connected app you’re creating is a canvas app, you can skip this field. The Canvas App URL field contains the URL that gets called for the connected app.
Select PIN Protect if your app supports PIN protection. This gives an admin the option of setting the session timeout and PIN length for mobile applications after installing the connected app. PIN protection is automatically supported by the Salesforce Mobile SDK (https://developer.salesforce.com/page/Mobile_SDK). You can also implement it manually by reading the mobile_policy object from the user’s Identity URL.
Specify the App Platform by choosing iOS or Android from the drop-down list.
Specify the supported device form factor(s) for the mobile app from the Restrict to Device Type drop-down list. The possible values are Phone, Tablet, or Mini-Tablet. If the app is universal (that is, supports all form factors), don’t choose any value.
Enter the App Version number of the mobile app.
Enter the Minimum OS Version required for the app.
Select Private App to confirm that this app is for internal (non-public) distribution only. This is required because Apple doesn’t allow distribution of public mobile apps outside of its app store.
If the mobile app is private, specify the location of the Mobile App Binary file. This is an IPA file for iOS and an APK file for Android.
For iOS apps only:
Specify the location of the Application Icon. This is the icon displayed during download and installation of the app on an iOS device.
Specify the iOS Bundle Identifier.
For iOS 7 and later, you must specify the same bundle identifier that you used for developing the app in XCode. Otherwise, the end user sees two app icons on app installation.
If the mobile connected app is a public app and you haven’t uploaded its binary file to Salesforce, enter the app binary URL here.
If you remove mobile integration from a new version of an existing connected app, mobile integration is no longer included in any version of the connected app. For example, imagine publishing a package containing version 1.0 of your connected app with mobile integration. Then remove mobile integration from the app, repackage it, and publish it as version 1.1. If a customer installs the earlier package with version 1.0 at this point, the version 1.0 connected app doesn’t contain mobile integration.
Your connected app can receive push notifications if:
Your app is built with Salesforce Mobile SDK.
Your app implements the Mobile SDK push notification protocol for your platform.
You are a registered developer with the mobile platform provider (Apple or Google).
Your app is registered with Apple Push Notification Service (APNS) for iOS push notifications or with Google Cloud Messaging (GCM) for Android push notifications.
You’ve implemented Apex handlers for push notifications.
A push-enabled connected app can support only one mobile platform. If you provide Android and iOS versions of your mobile app and must support push notifications on both versions, create a connected app for each platform.
To learn how to fulfill these requirements, see the Salesforce Mobile Push Notifications Implementation Guide.
To configure push notifications for APNS (iOS):
Select Push Messaging Enabled.
For Supported Push Platform, select Apple.
Select the Apple environment that is valid for your APNS push notifications certificate.
For Certificate, select the .p12 certificate file that you received from APNS when you registered your app for push notifications (for example, appkey.p12).
Enter the password for your .p12 certificate file.
To configure push notifications for GCM (Android):
Select Push Messaging Enabled.
For Supported Push Platform, select Android GCM.
For Key for Server Applications (API Key), enter the key that you obtained during developer registration with Google.
To change the mobile platform that you’ve configured for push notifications:
Deselect Push Messaging Enabled.
Save the connected app, and then click Edit.
Change App Platform and associated values in Mobile Settings to reflect the new platform.
Reconfigure push notifications for the new platform.
Canvas App Settings
Two types of canvas apps are available:
Canvas apps that the org’s Salesforce admin installed.
Canvas personal apps that end users installed across orgs. Users access a canvas personal app from the Chatter tab, and are prompted to allow the app to connect to their Salesforce data. They have the option to make an app a canvas personal app. For more information, see “Canvas Personal Apps” in the Force.com Canvas Developer’s Guide.
If your connected app is exposed as a canvas app, select Force.com Canvas.
Enter the canvas app URL to the third-party app. The user is directed to this URL when clicking the link to your canvas app.
Select an access method. This specifies how the canvas app initiates the OAuth authentication flow.
Signed Request (POST): OAuth authentication is used, but when Salesforce admins install the canvas app, they implicitly allow access for users. Therefore, users aren’t prompted to allow the third-party app to access their user information. When you use this access method, the authentication is posted directly to the canvas app URL.
If your canvas app uses signed request authentication, be sure that you don’t add Perform requests on your behalf at any time to the Selected OAuth Scopes.
OAuth Webflow (GET): OAuth authentication is used, and the user is prompted to allow the third-party app to access their information. When you use this access method, the canvas app must initiate the OAuth authentication flow.
If you’re using SAML single sign-on (SSO) for canvas app authentication, select the SAML Initiation Method field. This field is enabled if you select Enable SAML in the Web App Settings section. The options for this field include the following.
Identity Provider Initiated—Salesforce makes the initial request to start the SSO flow.
Service Provider Initiated—The canvas app starts the SSO flow after the app is invoked.
Under Locations, select where the canvas app appears to users.
Chatter Feed—The canvas app appears in the feed. If this option is selected, you must create a CanvasPost feed item and ensure that the current user has access to the canvas app.
Chatter Tab—The canvas app appears in the app navigation list on the Chatter tab. If this option is selected, the canvas app appears automatically.
Console—The canvas app appears in the footer or sidebars of the Salesforce console. If this option is selected, you must choose where the canvas app appears in a console by adding it as a custom console component.
Layouts and Mobile Cards—The canvas app can appear on a page layout or a mobile card. If this option is selected, you choose where the canvas app appears by adding it to the page layout.
Mobile Nav—The canvas app is accessible from the navigation menu in Salesforce1.
Canvas apps don’t appear in the Salesforce1 navigation menu on Android mobile devices. To see canvas apps in the navigation menu, log in to the Salesforce1 mobile browser app.
Open CTI—The canvas app appears in the call control tool. If this option is selected, you must specify the canvas app in your call center’s definition file for it to appear.
Publisher—The canvas app appears in the publisher. If this option is selected, you must also create a canvas custom quick action and add it to the global layout or to an object layout.
Visualforce Page—The canvas app can appear on a Visualforce page. If you add an <apex:canvasApp> component to expose a canvas app on a Visualforce page, be sure to select this location for the canvas app; otherwise, you receive an error.
Select Create Actions Automatically to create a global action for your canvas app. To create a global action for the canvas app, you must select Publisher under Location; otherwise, no global actions are created. You can also create the action manually later.
If you’ve implemented your own Canvas.CanvasLifecycleHandler Apex class, provide the class name in Lifecycle Class. Providing a CanvasLifecycleHandler Apex class lets you customize context information and add custom behavior to your canvas app.
To let end users install your app, select Enable as a Canvas Personal App. Chatter Tab is the only location that supports canvas personal apps. For details about canvas personal apps, see “Canvas Personal Apps” in the Force.com Canvas Developer’s Guide.
If you don’t see the Enable as a Canvas Personal App setting, the admin for the app’s destination org hasn’t enabled canvas personal apps. For details about this requirement, see “Enabling Canvas Personal Apps within an Organization” in the Force.com Canvas Developer’s Guide.