Integrating Applications As Heroku Add-Ons

Heroku is a popular Platform-as-a-Service provider and it offers vendors the option to be provided as add-ons. Add-ons can be used by Heroku customers in different ways, but a typical scenario would be “Start a database”, “Start an MQ”, or “Start a logging solution”. After you add the add-on to your account, you can connect to the chosen database, MQ, logging solution or whatever.

Integrating as Heroku add-on is allegedly simple, and Heroku provides good documentation on how to do it. However, there are some pitfalls and so I’d like to share my experience in providing our services (Sentinel Trails and SentinelDB) as Heroku add-ons.

Both are SaaS (one is a logging solution, the other one – a cloud datastore), and so when a Heroku customer wants to add it to their account, we have to just create an account for them on our end.

In order to integrate with Heroku, you need to implement several endpoints:

  • provisioning – the initial creation of the resources (= account)
  • plan change – since Heroku supports multiple subscription plans, this should also be reflected on your end
  • deprovisioning – if a user stops using your service, you may want to free some resources
  • SSO – allows users to log in your service by clicking an icon in the Heroku console.

Implementing these endpoints following the tutorial should be straightforward, but it isn’t exactly. Hence I’m sharing our Spring MVC controller that handles it – you can check it here.

A few important bits:

  • You may choose not to obtain a token if you don’t plan to interact with the Heroku API further.
  • We are registering the user with a fake email in the form of <resourceId> However, you may choose to use the token to fetch the emails of team members and collaborators, as described here.
  • The most important piece of data is the resource_id – store it in your users (or organizations) table and consider adding an index to be able to retrieve records by it quickly.
  • Return your keys and secrets as part of the provisioning request. They will be set as environment variables in Heroku
  • All of the requests are made from the Heroku servers to your server directly, except the SSO call. It is invoked in the browsers and so you should set the session cookie/token in the response. That way the user will be logged in your service.
  • When you generate your addon manifest, make sure you update the endpoint URLs

After you’re done, the alpha version appears in the marketplace (e.g. here and here). You should then have some alpha users to test the add-ons before it can be visible in the marketplace.

Integrating SaaS solutions with existing cloud providers is a good thing, and I’m happy that Heroku provides an automated way to do that. (AWS, for example, also has a marketplace, but integration there feels a bit strange and unpolished (I’ve hit some issues that were manually resolved by the AWS team).

Since many companies are choosing IaaS or PaaS for their services, having the ability to easily integrate an add-on service is very useful. I’d even go further and propose some level standardization for cloud add-ons, but I guess time will tell if we really need it, or we can spare a few days per provider.

2 thoughts on “Integrating Applications As Heroku Add-Ons”

  1. Bozho,

    Thanks for writing this up! I work as the Lead Integration Engineer for the Heroku add-on marketplace. I’d love to hear more about your experiences working with our (and other!) marketplaces, I want to ensure we have the easiest and most comprehensive integration possible.

    One comment- you’re correct that it’s not required to exchange the grant token during provisioning for a basic integration, but forgoing that means you miss:

    * an easy way to do [asynchronous provisioning](, which fits better into the “eventually consistent” nature of modern cloud environments
    * the ability to do [automated credential rotations](, something we hear from customers more and more as they seek to function under more common compliance regimes
    * being able to retrieve “advanced” metadata about apps using your add-on, which includes users, teams, pipeline info, webhooks and runtime info. This can be very helpful to add-on partners that want to make richer integrations with Heroku apps, providing a better experience for our shared customers

    We can help you backfill grant tokens later, but it’s just more work for everyone. Anyway, great write-up!

  2. Thanks for the additional links. (The spam filter was overcautious, so I had to manually approve the comment).

Leave a Reply

Your email address will not be published.