Connected App User Guide

A “Connected App” is an application that can connect to salesforce.com over Identity and Data APIs. Connected Apps use the standard OAuth 2.0 protocol to authenticate, provide Single Sign-On, and acquire access tokens for use with Salesforce APIs. In addition to the standard OAuth capabilities supported by the existing Remote Apps feature (which Connected Apps is designed to replace), Connected Apps add additional levels of control, allowing administrators explicit control over who can use the application, and various security policies to be enforced by the application.

All apps built and deployed using MobileCaddy and a MobileCaddy Container app (the installable application for iOS, Android and Windows Desktop) will use a ‘Connected App’. As described more fully below these can either be Connected Apps created and maintained by MobileCaddy or specific Connected Apps created for each new project/app.

Connected Apps are created in a single Salesforce org and then are ‘installed’ into an Org once an external application that uses the Connected App authenticates. Note – they do not need to be deployed using changesets, and once created are available for use on Developer, Sandbox, and Production Orgs.

NOTE – Do NOT create your Connected Apps in a Sandbox environment.

Decisions

To create a Connected App the following items should be considered:

  • Where will you create your Connected App?
  • Which Operating Systems are you users going to be running (this will affect the number of Connected Apps you need to create)
  • Will you be using SSO (Single Sign On). This may affect some Connected App settings (refer to your SSO provider for further information)
  • How and what can you change for the Standard login screen for your users (ie branding)

Why use Connected Apps

The use of connected apps support;

  • Custom Branding – Each Connected App can be be given it’s own name and image that appear on the “Allow Access” oauth screen.
  • Security
    • Provides oAuth mechanism to allow secure one-time login to apps. Mean that there is no storage of passwords in the MobileCaddy application or device (iOS, Android, Windows Desktop)
    • Provides a mean to disable access (org-wide) to a specific container app.
  • Allows for push notifications services to be associated and enabled

Limitations of Connected Apps

  • Some options of a Connected App can only be configured in the Org that was used to create the Connected App.
  • Salesforce only allow 4 concurrent OAuth tokens for each Connected App per Salesforce user.
  • Only one ‘Push’ platform can be assigned to each Connected App (ie Apple OR Android). Therefore it is recommended for future proofing that each OS supported has a dedicated Connected App created.

Creating & Defining

Valid Connected App Creation Environments

Connected Apps are created in a single Salesforce org and then are ‘installed’ into an Org once an external application that uses the Connected App authenticates. Note – they do not need to be deployed using changesets, and once created are available for use on Developer, Sandbox, and Production Orgs.

Valid connected app creation environments are – in preferential order;

  1. Production (Preferred)
  2. Packaging Org (If you have one)
  3. Partner Dev Org

NOTE Sandbox environments SHOULD NOT be used to create Connected Apps (this is due to the fact that if the Sandbox is refreshed then the ability to manage the Connected App will be lost)

Creating a Connected App

To create a Connected App, in one of the valid environments, navigate to Setup > Create > Apps. In this page there is a section ‘Connected Apps’. Select the ‘New’ button to start adding the details below.

Screen 1 – you complete the the first initial details then press Save. Afterwhich you can then

Basic Information Section
  • Connected App Name (required)
  • API Name (required)
  • Contact Email (required)
  • Contact Phone
  • Logo Image URL
  • Icon URL
  • Info URL
  • Description
API (Enable OAuth Settings)
  • Enable OAuth Settings → CHECK
  • Enable for Device Flow → LEAVE UNCHECKED
  • Callback URL – This is dependent on the OS that is to be used with this Connected App
    • Android → sfdc://mobileCaddyAndroid
    • iOS → sfdc://mobileCaddy
    • Windows Desktop → sfdc://mobilecaddyWin32
  • Use Digital Signatures → LEAVE UNCHECKED
  • Selected oAuth Scopes – Select the following;
    • “Perform requests on your behalf at any time”
    • “Provide access to your data via the Web”
    • “Access and manage your data”
  • Require Secret for Web Server Flow → LEAVE UNCHECKED
  • Include ID Token → LEAVE UNCHECKED
  • Enable Asset Tokens → LEAVE UNCHECKED
Web App Settings Section
  • Start URL → LEAVE BLANK
  • Enable SAML → If SSO is required please contact MobileCaddy for further information, as this can differ case-to-case
Custom Connected App Handler Section
  • Apex Plugin Class → LEAVE BLANK
  • Run As → LEAVE BLANK
Mobile App Settings Section
  • Mobile Start URL → LEAVE BLANK
  • PIN Protect → LEAVE UNCHECKED
  • App Platform → LEAVE BLANK
  • Restrict to Device Type → LEAVE BLANK
  • App Version → LEAVE BLANK
  • Minimum OS Version → LEAVE BLANK
  • Private App → LEAVE UNCHECKED
  • App Binary → LEAVE BLANK
  • Push Messaging Enabled → LEAVE BLANK
Canvas App Settings
  • Force.com Canvas→ LEAVE UNCHECKED

At this point select ‘Save’ to commit the above and create the Connected App. The Connected App can take up to 10 mins to be available use.

Once created you will get a Consumer Key and a Consumer Secret (you can find these by clicking on the Connected App name in the list of Connected Apps – this will show the Consumer Key. The Consumer Key will not be shown by default.

The Consumer Secret should not be shared with anyone.
MobileCaddy require the Consumer Key, not the Consumer Secret, to create the container app.

Once you have these details and your Connected App has been saved (for your OS(s)) a Container App Asset Request form will need to be filled in so that the Container App can be created.

IP Restrictions. Note once the Connected App is created it will inherit the default setting of enforcing IP restrictions. To relax this policy navigate to Connected Apps and ‘Manage’ your newly created Connected App. Here you can relax the IP settings if required.

See Defining Connected Apps for further information from Salesforce on creating Connected Apps.

Notes

If Salesforce Community users will be running the application then as well as the Connected App info required to create the build files you will also require the Community URLs (ideally for production and all development environments)

SSO – Connected App will need to be defined prior to setting up the SSO options

Further Reading