ISVforce 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

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”
Follow these steps to create a connected app:
  1. From Setup, click Create | Apps.
  2. In the Connected Apps section, click New.
The information required to create a connected app is divided into these parts:
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.
  1. Enter the Connected App Name. This name is displayed in the list of connected apps.

    The name must be unique for the current connected apps in your organization. You can reuse the name of a deleted connected app if the connected app was created using the Spring ’14 release or later. You cannot reuse the name of a deleted connected app if the connected app was created using an earlier release.

    Note

  2. 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.
  3. Provide the Contact Email that salesforce.com should use for contacting you or your support team. This address is not provided to administrators installing the app.
  4. Provide the Contact Phone for salesforce.com to use in case we need to contact you. This number is not provided to administrators installing the app.
  5. 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.
  6. 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.

  7. If there is a a Web page with more information about your app, provide a Info URL.
  8. Enter a Description to be displayed in the list of connected apps.
Prior to Winter ’14, the Start URL and Mobile Start URL were defined in this section. These fields can now be found under Web App Settings and Mobile App Settings below.

API (Enable OAuth Settings)

This section controls how your app communicates with Salesforce. Select Enable OAuth Settings to configure authentication settings.
  1. Enter the Callback URL (endpoint) that Salesforce calls back to your application during OAuth; it’s the OAuth redirect_uri.
  2. 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.
  3. 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.
    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. 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.

If you upload a certificate, all SAML requests must be signed. If no certificate is uploaded, all SAML requests are accepted.

Important

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

If your app is a mobile app, 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 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.

Pin protection is automatically supported by the Salesforce Mobile SDK (http://developer.force.com/mobilesdk). You can also implement it manually by reading the mobile_policy object from the user’s Identity URL. If your app enforces it, select Pin Protect to give an administrator the option of setting the session timeout and PIN length for mobile applications after installing the connected app.

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 will not contain mobile integration.

Note

Canvas App Settings

  1. If your connected app will be exposed as a canvas app, select Force.com Canvas.
  2. 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.
  3. 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. Signed request authorization never returns a refresh token, even if this field value is selected.

    • 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.
  4. 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.
    • 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 action and add it to the global layout or to an object layout.
    • Salesforce 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.
    • 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.
  5. 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.