ISVforce Guide
jNewer Version Available
Creating a Connected App
|
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 read: | “Customize Application” |
| 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: | “Customize Application” |
| To update Profiles, Permission Sets, and Service Provider SAML Attributes: | “Customize Application” AND “Modify All Data” |
| To uninstall: | “Download AppExchange Packages” |
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 should prompt 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
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.
Basic Information
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 list of connected apps.
- 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 you’ll need to edit the default name if the original app name contained any other characters.
- Provide the Contact Email that Salesforce should use for contacting you or your support team. This address is not provided to administrators installing the app.
- Provide the Contact Phone for Salesforce to use in case we need to contact you. This number is not provided to administrators installing the app.
- Enter a Logo Image URL to display your logo
in the list of connected apps and on the consent page that users see when authenticating.
The URL must use HTTPS. The logo image can’t be larger than
125 pixels high or 200 pixels wide, and must be in the GIF, JPG, or
PNG file format with a 100 KB maximum file size. The default logo
is a cloud. You have several ways to add a custom logo.
- 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 the logo meets the size requirements.
- You can also select a logo from the samples provided by clicking Choose one of our sample logos. The logos available include ones for Salesforce apps, third-party apps, and standards bodies. Click the logo you want, and then copy and paste the displayed URL into the Logo Image URL field.
- You can use a logo hosted publicly on Salesforce servers by uploading an image that meets the logo file requirements (125 pixels high or 200 pixels wide, maximum, and in the GIF, JPG, or PNG file format with a 100 KB maximum file size) as a document using the Documents tab. Then, view the image to get the URL, and 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. The
logo should be 16 pixels high and wide, on a white background. Sample
logos are also available for icons.
You can select an icon from the samples provided by clicking 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 a Web page with more information about your app, provide a Info URL.
- Enter a Description to be displayed in the list of connected apps.
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, this is typically the URL that a user’s browser is redirected to after successful authentication. As this URL is used for some OAuth flows to pass an access token, the URL must use secure HTTP (HTTPS) or a custom URI scheme. If you enter multiple callback URLs, at run time Salesforce matches the callback URL value specified by the application 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 organization associated with the connected app, and 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 does not return a refresh token. You must explicitly request the refresh_token scope to get a refresh token.
- 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.
If your organization had the No user approval required for users in this organization option selected on your remote access prior to the Spring ’12 release, users in the same organization 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 checkbox is selected to show this condition. For connected apps, the recommended procedure after you’ve created an app is for administrators to install the app and then set Permitted Users to Admin-approved users. If the remote access option was not checked originally, the checkbox 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 will be 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.
If your connected app will use 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.
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).
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 will be sent to the Start URL defined under Web App Settings. If the connected app you’re creating is a canvas app, 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.
- Select PIN Protect, if your app supports PIN protection. This gives an administrator 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 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.
- 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.
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.
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 are installed by the organization administrator.
- Canvas personal apps that are installed by end users across organizations. Users access a canvas personal app from the Chatter tab, and are prompted to allow the app to connect to their Salesforce data. These steps include optionally making 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 will be exposed as a canvas app, select Force.com Canvas.
- Type the Canvas App URL to the third-party app. The user is directed to this URL when they click 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 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.
If your canvas app uses signed request authentication, then be sure 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 application to access their information. When you use this access method, the canvas app must initiate the OAuth authentication flow.
-
Signed Request (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.
- 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 are:
- 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 there automatically.
- Console—The canvas app appears in the footer or sidebars of a 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.
- 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’ll 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 at a later time.
- 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 make your app installable by end users, select the Enable as a Canvas Personal App checkbox. 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.