Implementing Roles for Heroku Users in Add-on SSO Dashboards
Last updated February 06, 2024
Table of Contents
If your add-on is attached to a Heroku app that has multiple collaborators, all of those collaborators can open the add-on’s dashboard via add-on SSO. Optionally, your add-on can define its own set of roles that it assigns to these collaborators. This enables the app’s owner to restrict access to certain dashboard features.
This article describes how to create and maintain roles for your add-on dashboard without violating the add-on ownership model.
Most importantly, never create a username and/or password in your system for a Heroku add-on user. Always authenticate add-on users via add-on SSO.
Always set a default role for new SSO users
Whenever a collaborator opens your add-on’s dashboard via add-on SSO, the request to your system includes an email parameter. This is the email address associated with the collaborator’s Heroku account.
Assuming the SSO request authenticates successfully:
- If this is the first user ever to authenticate for this add-on instance, assign the user an “admin” role that has full dashboard permissions.
- “Full dashboard permissions” should include the ability to change the role of other collaborators that authenticate in the future.
- If this is a new user that isn’t the very first user to authenticate, assign the user whatever “default” role makes sense for your add-on’s dashboard (this might be the same “admin” role as above).
- If this user has authenticated before, assign them whatever role is currently associated with their email address in your system.
After assigning a role to a user, make sure to persist it with the user’s email address in your system.
When your dashboard determines a user’s role, it can then present its UI in accordance with that role’s permissions.
It’s recommended that your system always require at least one active user to have the “admin” role for a given add-on instance. Otherwise, a scenario can more commonly arise where no users have full dashboard access.
Note that even if your system does enforce this requirement, all users with the “admin” role might later be removed from the add-on’s associated app. In this case, the app’s owner will need to file a support ticket that you as the add-on provider will be assigned.
Automatically determining roles for team-owned apps
If an app is owned by a Heroku Team, you can optionally use the endpoints described in Syncing User Access as an Ecosystem Partner to determine whether a particular user is an “admin” or a “member” of that team. If your add-on’s dashboard uses a similar two-role structure, you can simply determine an appropriate dashboard role from a user’s team role.