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>@heroku.com. 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
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.