Marketplace distribution of external services

Updated on 06-April-2017 at 11:26 AM

Business Catalyst End of life announcement - find out more details.

Redirect URI

For this type of service, it is mandatory to provide an https redirect uri when registering your external service which will act as your OAuth callback. You will be notified when a BC Partner has requested or cancelled a subscription for your external service.

After each notification received from BC to your secure redirect uri, you have the information needed to keep your own records of the subscribers to your service and with the authorization code you can go further and get the access and/or refresh token needed for your service.

Note: It is strongly recommended to have a certificate signed by an authorized Authority (e.g VeriSign) on your site.

Requirements

  • Client ID - this is available by going to Partner Portal -> My Apps -> [Your App Id ] 
  • Version - the app's version.
  • Redirect URI - the secure link of the page that will act as your OAuth callback.
  • Client secret - this is available by going to Partner Portal -> My Apps -> [Your app's name]

Business Catalyst provides a standard extensible mechanism through Open Platform applications. From a security point of view this is achieved through The OAuth 2.0 Authorization Framework.

At the moment there are two kind of applications which can integrate with Business Catalyst:

  1. Admin Console Apps (JS based applications which can be launched only from Admin Console), they are launched on a dedicated secure app domain and displayed in the Admin Console using an iframe.
  2. External services that have been exemplified in more detail in the Server to server service article, they can be external websites, mobile applications, TV apps and so on.

The above mentioned applications can be distributed in Adobe Business Catalyst using two channels:

  1. Within the same partner portal, a partner can manually distribute his apps to his customers.
  2. Cross Partner Portal, BC App Store orchestrates the distribution of apps.

After you have entered the App Developer Program, the BC App Store will provide you with an easy way of distributing your external service (which optionally might have an Admin Console frontend app) to the Adobe Business Catalyst community.

Please follow the workflows below for the installation and cancellation processes.

Installation Workflow

The marketplace will be the middle man between the BC Partner that wants to install a certain service / external application and Business Catalyst.

1. Marketplace Frontend

The frontend for you external service will be provided by BC App Store, please check the apps page and select an already created application to get an idea of how you can market your app.

This is where the BC Partner will choose your external service to install.

2. Initiate authorization request

The marketplace redirects the BC Partner to the BC authorize endpoint.

If the partner is not logged in, he will need to authenticate and after succesful authentication BC will ask consent for installing the requested external service.

3. Application installation

Marketplace will install the application to the partners selected sites, if it has an admin component.

4. Send authorization code to service

After some server side magic the your external service will be notified using the following method:

POST on <service_redirect_uri>

Parameters
  • client_id - the external service/application ID.
  • version - the version of the external service/application specified above.
  • response_type - it will equal code
  • code - the authorization_code
  • redirect_uri - the uri registered in the Partner Portal application page
  • state - a cryptographic signature algorithm that will equal see section
  • sideIds - comma separated site id values

Cancellation Workflow

1. Marketplace Frontend

From the BC App Store the partner will be able to trigger a cancellation of his subscription to the external service/app on one or more sites.

2. Initiate cancellation

The Marketplace redirects the BC Partner to the BC authorize endpoint.

If the partner is not logged in, he will need to authenticate.

Afterwards BC will ask consent for cancelling the subscription and will cancel entitlements for the site or sites selected.

3. Send cancellation notification to service

The external service will be notified that a subscription has been cancelled from the Marketplace using the following method:

POST on <service_redirect_uri>

Parameters
  • client_id - the external service/application ID.
  • version - the version of the external service/application specified above.
  • response_type - it will equal cancel-response
  • sideIds - comma separated site id values where the subscription has been cancelled
  • redirect_uri - the uri registered in the Partner Portal application page
  • state - a cryptographic signature algorithm that will equal see section

State cryptographic signature algorithm

We use state query parameter as an additional security measure for you to check the requesters' identity.

Below you can find the algorithm which can be used for verifying the state:

state = hmac(client_secret, https://<host>:443/?<query_parameter_list>)

Each item from query parameter list is in form of: param_name=urlencode(param_value).
The query parameter list must be ordered alphabetically by parameter name.