Connected Apps allow non-Salesforce apps to act on behalf of a Salesforce user. For example:

  • Send your user information to another system with a single click.
  • Allow another system to send information into your Salesforce API.

They are a policy how to "borrow" a Session ID for specific uses.

Must a Connected App always be used for authorization?

No. A few cases involve authorization with no Connected App:

  1. An Outbound Message workflow action can create a Session ID any selected user. The pre-authorization is implied by an administrator (who trusts the receiving system) configuring the Workflow Rule.
  2. An interactive Visualforce Page can use its own Session ID to call eg the REST API. Again, the Visualforce Page was created by a trusted administrator and any callout is designed to do trustworthy stuff.
  3. An internal company system could use a stored Username / Security Token / Password to log into Salesforce and obtain a Session ID. This is a last resort, willingly giving the system raw login credentials.

Handing over a Session ID to any third party is handing over a loaded gun. It means full and unfettered access with uncontrolled scope. Because using a Session ID may extend its expiration date, any raw Session ID is potentially as risky as any raw login credential.

Why use a Connected App?

Using OAuth with a Connected App has advantages:

  • Usage is tracked and auditable.
  • Power of granted access can be reduced.
  • Limit granted access to a certain time period.
  • Revoke granted access without having to change your password.
  • Password can be changed without having to update other systems.

Salesforce use Connected Apps for their own products: Workbench, Salesforce1, Environment Hub. At no point do these products handle credentials; it's best practice.

Are access_tokens and refresh_tokens like loaded guns too?

Yes. But the bullets are revokable. And possibly reduced in power.

For ISV Developers

Must a Connected App be part of a package?

No. Generally, developers can perform assertions and get access tokens without an installed package. Generally users can authorize a Connected App without any installed package.

What are examples when my Connected App has to be installed?

Installation is required when:

  • admins want to pre-authorize a Connected App without user interaction
  • org-specific policies like Login IP Restrictions need to be relaxed on the app

Any existing Connected App can be installed and consumed without need for a managed or unmanaged package. This separate process is not to be confused with the prior creation of the Connected App definition itself.

I'm a developer. How to install a Connected App without a package?

Per above, generally you don't have to. Installation and consumption of a Connected App is mutually exclusive of and independent from managed or unmanaged packages.

In the non-general cases, Salesforce provides a special function that completely bypasses the ISV packaging or installation lifecycle. Developers can provide a special URL to the consumer of the app:

  1. Log into the organization where the Connected App is defined
  2. Go to Setup > Create > Apps, then navigate to the connected app
  3. Extract the 'id' URL parameter (it starts with OCi) and paste into a new link:

The screen is the same as users would get themselves by navigating to Connected Apps OAuth Usage in their setup menu.

Why not put the Connected App in the managed package?

Not all products involve a managed package, see hosted or off-platform integrations as examples.

In cases where there is a package, the app can complicate package development. Normally, a single Client ID or Consumer Key is held in a secret constant available only to the packaging org.

Because Connected App definitions are expected to be globally unique across the entire Salesforce ecosystem, deploying a Connected App from source control requires a unique Client ID or Consumer Key to be generated each time.

Bear in mind however, this extra step may indeed be desirable in the case of open source products where the package is intended to be a standalone instance, 100% under the control of each deployer.

For App Consumers

I'm an administrator. How to install a Connected App without a package?

Salesforce provides an interface for admins in the consumer organization if (and only if) the Connected App authorization URL flow has been successfully completed by at least one user:

  1. Log into the org and follow the authorization flow for the application
  2. Go to Setup > Connected Apps > Connected Apps OAuth Usage
  3. Find the appropriate row and click the Install action
  4. Follow the on screen instructions

The ability to Manage App Policies will now become enabled.

I really trust this app. How can all users skip the authorization nag?

In contrast to the self-authorized OAuth flow, apps can indeed be pre-authorized on selected Profiles and Permission Sets:

  1. Install the Connected App into the org per above
  2. Go to Setup > Connected Apps > Manage Apps > Edit Policies
  3. Change "Permitted Users" to "Admin approved users are pre-authorized" then save
  4. Find the desired Profile or Permission Set then navigate to Connected App Access
  5. Enable the app then save. (If the app isn't visible, install it first per above)

Why do I see "Insufficient Privileges" during the OAuth flow?

There are two causes:

  1. The user does not have a password. This can happen from user creation if "Generate new password" is unchecked. A solution is to hit "Reset Password" on the user record and go through the reset process from the email. Then OAuth flows will work.
  2. If the running user context is "Login As", participation in OAuth flows are not allowed. A solution is to log fully via username and password. If this is not possible, the Connected App can be enabled via profiles or permission sets which skips the authorization flow entirely.

How can I create a connected app which can have different callback URL in each different consumer org?

Some ideas as a starting point for experiments:
- deploy custom Connected App using Metadata API and setup screen
- use org-agnostic / as the callback URL
- use an intermediate site as the callback URL and redirect each consumer individually