What Is This Article About?

We have seen some very impressive adoption rate amongst our customers and ISV partners in leveraging Canvas framework for building integrated composite applications on Salesforce1 Platform. Based on some of the lessons learned and feedback received, we decided to publish this article to help our ISV partners understand their options when it comes to packaging Canvas for distribution and for support of different Salesforce1 platform editions.

Canvas Summary

Let’s start with a very brief recap of what Canvas is and why you would use Canvas in the first place. Canvas is an integration framework that allows partners to easily integrate third-party applications with Salesforce1 Platform. Canvas allows ISVs to expose an externally hosted application inside the Canvas container and have very meaningful and seamless UI and API based integration between them. Canvas includes a whole host of tools and frameworks such as Authentication (OAuth), Support for Cross-domain XHR, Javascript-based events framework, and tools for embedding your app in Visualforce pages, Chatter Publisher actions and even Salesforce1 Mobile Application Container. Please see the Canvas Developer Doc for more details on all of the above as well as all other information you may need to build your solution. For the remainder of this article, we will assume that you have gotten up to speed and developed either a prototype or a release-ready version of your Canvas solution and are now ready to package it for distribution.

Access Method and Permitted Users

Canvas is defined as part of the Connected App metadata entity which has a number of settings and attributes and we are adding new ones with each release. In this article, we are going to specifically focus on two attributes of the Connected App component that are particularly important when it comes to packaging: Access Method and Permitted Users.

Access Method

Access Method is defined when you create the Connected App definition and enable Canvas as shown below:

Connected App - Access Method

Path in dev or packaging org: Setup > Build > Create > Apps > Connected Apps > New

Access method is defined by the Developer of the package. Once the Connected App is placed inside a managed package, the Access Method attribute can no longer be changed.

Currently, access method has two available options:

  1. Signed Request (POST) – this is the default method of authentication for canvas apps in which the signed request containing the consumer secret, context and authorization token are provided to the canvas app. The developer does not need to implement the OAuth authentication flow since the authorization token is passed to the external application as part of the request.
  2. OAuth Web Request (GET) – with this method, Canvas apps can use the OAuth 2.0 protocol to authenticate and acquire access tokens. For more information about OAuth and the Salesforce1 platform please check out this article.

Permitted Users

Permitted Users is a setting that a customer admin can control. Once a managed package with the ConnectedApp is installed in a customer org, the admin can choose one of the below two settings:

Connected App - Permitted Users Path in Customer Org: Setup > Administer > Manage > Connected Apps > [Name of Installed App] > Edit

  1. All users may self-authorize – end users will have to self-authorize Canvas app access via OAuth authorization dialog.

  2. Admin approved users are pre-authorized – end users will not see the OAuth authorization dialog, the authorization flow will run implicitly transparent to the user. This requires Permission Sets or Profiles to be available in the org in order for an admin to grant users access to the ConnectedApp.

How These Settings Work Together

Here is the table summarizing possible options and below is the description to illustrate what will happen depending on which settings are selected.

Canvas packaging in different editions table

OAuth (Web Request) Connected Apps are currently accessible by all users in all editions including Group, Professional and above. When the Web Request ConnectedApp is installed in the customer org, as part of the initial configuration, the admin can select OAuth Policy setting for Permitted Users to be either “All users may self-authorize” or “Admin approved users are pre-authorized”. The latter requires the access to be granted via Permission Sets or Profiles and therefore may not be available in most PE/GE orgs where Profiles and Permissions Sets are not enabled. You can see the detailed flow diagram for the OAuth (Web Request) Connected App here.

Signed Request Connected Apps require Profiles or Permission Sets feature in order for the org admin to grant users access to the app. Profiles and Permission Sets are advanced features and are not included in PE edition and lower by default. Effectively this means that as of today, most typical Group and Professional Edition customers are not going to be able to use your Signed Request Connected App unless they upgrade to EE or higher or purchase these features as an add-on. You can see the detailed flow diagram for the Signed Request Connected App here.

So, What Does It All Mean When It Comes to Packaging?

Let’s break it down based on what type of editions your application needs to support starting with the simplest example first.

Supporting ONLY Enterprise and Above

Since all orgs of Enterprise Edition and above have Profiles and Permission Sets on by default you can package either Signed Request or Web Request Connected App without any problem. The former is your default option and is somewhat simpler because it does not require implementation of the OAuth token exchange routine.

Supporting ONLY Professional and Group

Since Profiles and Permission sets are not available in majority of PE/GE editions, you can only offer OAuth Web Request Connected App to those customers as of today. It is possible for your customers to purchase Profile and Permission Sets as an add-on for PE/GE orgs, however, in many cases, this may not be practical either due to extra cost or because it adds a layer of complexity to your sales cycle.

Supporting All Editions

Finally, possibly more common scenario is when you would like to offer your application to all of our customers from Group Edition and up. Here are your options:

Option 1 (Recommended): Provide only OAuth Web Request (GET) Connected App.

  • Pro: Easy in terms of packaging, one Connected App component for all editions.

  • Con: Slightly more technically complex requiring the implementation of OAuth token exchange process.

Option 2: Provide two connected apps. Signed Request for EE and above and OAuth Web Request for PE and below.

  • Pro: you have the flexibility to implement either authorization flow

  • Con: it makes your packaging and application design more complex

If you do decide to go this route, there are two potential solutions for being able to offer both types of Connected Apps:

  1. Single Package: your package will contain both apps and any components referencing these two apps need to duplicated or be made dynamic based on edition in which the app installed. To determine the org edition, you can use the below Query:  select OrganizationType from Organization

    Disclaimer: I did not test this myself as of yet. If you do implement this, please send me some feedback so I can update the article with best practices from our partner community.

  1. Multiple Packages: Alternatively, you could define separate packages for EE vs PE orgs. This is not something we would typically recommend as such duplication may increase your overhead and complicate your testing and development process. However, in some circumstances it may make sense. For example, you already have such package separation in place due to other reasons.

Testing

Ok, hopefully at this point, you determined your design approach and packaged your Canvas and Connected App in a Beta package. Before marking the package as released, you need to test the application against all the supported editions to make sure it works as expected. Normally, in order to test your application, you would go to the partner portal and create test orgs here, at least one for each supported edition. This case is no exception, please make sure to test against all editions by following the same process. Remember, as of today, the Connected App component cannot be deprecated. We are working on adding deprecation to more metadata components with each release, but for now, please make sure you test diligently against all editions before flipping the flag on your package to ‘Managed Released’.

One more tidbit regarding Professional Edition orgs. As you know, many (most) PE/GE orgs do not have API enabled. However, for the purposes of testing, when you create a test PE org from the partner portal, it will have the API turned on. The reason we did this is to allow you to test your apps that leverage API while your app is in development. Once your app passes the certification and gets officially listed on AppExchange, you can request a partner API token that will allow your application to use API even in PE/GE editions where API is not turned on for the customer.

Hopefully, this article will help you navigate your options for packaging your Canvas app and feel confident when packaging your app for distribution. Please send your comments and feedback!

Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS