Last updated 13 July 2020

Multiple Heroku users can access an add-on through the Add-ons single sign-on integration. Their authorization for a given add-on is based on the attached app’s permissions.

Today, the SSO integration only tells the add-on partner the Heroku user’s email address. Originally, it was intended that the email address might just be used for display, to indicate that the add-on knows who the user is and that they are authorized. However, add-ons often have their own login systems, or use third-party OAuth to services like GitHub to gain additional capabilities. Add-on parters would like to consolidate these user records with the requests coming in from Add-ons SSO requests. Partners also need to know when to revoke access outside of the typical Add-ons SSO requests when things like third party OAuth logins have been used.

This article shows an implementation of a user access list, utilizing the Platform API for Partners.

Prerequisites

• Access and use of the Platform API for Partners
• Recording Heroku add-on resource UUIDs on provision or by fetching from the existing Get App Info API endpoint – we highly recommend that you start saving them off of the Get App Info API if you aren’t already, since the resource UUID will never change and is the primary ID for accessing the Platform API for Partners.

Concepts

There are two concepts in Heroku that you must be familiar with to build this functionality.

The first concept is app collaborators. These are users which have been granted access to an app by an app’s owner.

The second concept is an Team and the team’s member list. A user can appear on either an app’s collaborators list, or on a member list of an team which owns an app. You will have to request both the app’s collaborators list and the team members list to build a full list of users with access to an add-on.

Implementation

To get a full list of Heroku users with access to an app, you’ll need to request:

• GET https://api.heroku.com/addons/:resource_uuid -> grab the app name
• GET /apps/:app_name/collaborators -> A list of app collaborator users
• GET /apps/:app_name -> Check for “team” object as part of the serialized response, save the Team’s UUID if present.
• If team app per above: GET /teams/:team_uuid/members - you’ll want role: "member" in particular out of this list

To detect whether an app is owned by an org, you will look in GET /apps/:app_name’s response for an "team" object. Pull out the Team’s UUID from this object. Then request the GET /teams/:org_uuid/members endpoint and select the records that have role: "member" in that list. Combine this list with the app collaborators list from above. If the email address given during the SSO request appears in this combined list, that user should be able to access the add-on for the specified application.

You need to repeat this process for each app in question, using the resource-scoped token for that application under the Platform API for Partners.

In the future, we’d like to open up some sort of standardized endpoint that indicates what users an add-on has access to through all apps or particular apps, but we don’t have that pattern for indicating access in our API yet. If you have suggestions for how such an endpoint might work, please get in touch with the Ecosystem team.