Last updated February 06, 2024

Heroku add-ons are owned by the Heroku application they’re provisioned for, not the Heroku user that provisioned them. This article describes the implications of this add-on ownership model and provides guidelines for correctly authenticating Heroku users that log in to your add-on’s dashboard via SSO.

Representing add-on ownership in your infrastructure

Because an add-on is owned by the Heroku application it’s provisioned for, its dashboard should be accessible by all Heroku users that are admins, owners, or collaborators for that application. An add-on’s dashboard should not be accessible by a Heroku user that does not have any of these roles, even if that user originally provisioned the add-on.

Consequently, when you create an account in your system to correspond to a newly provisioned add-on instance, do not associate the provisioning Heroku user’s information with any fields related to authentication. Instead, create a “shadow user” for each provisioned add-on instance. This user is not associated with any individual person, and it can only be authenticated via add-on SSO (not via username and password).

Authenticate via SSO only

When Heroku app users open your add-on’s web dashboard, they authenticate via add-on SSO. This is the only authentication method that your web service should allow for Heroku app users.

• Do not create a username and password (i.e., an alternate authentication method) in your system for the account of a Heroku add-on user.
• Do not persist any authentication privileges for the specific email address included in an add-on SSO request.
• Do not cache lists of authorized users for a particular add-on. If this causes performance issues, invalidate cache entries at least once every five minutes.

These guidelines are important because the owners of a Heroku app might change at any time. Only a valid SSO request guarantees that a user attempting to log in on behalf of a Heroku app is indeed authorized to do so.

Customizing your add-on SSO dashboard

Your SSO dashboard should not have functions that allow an authenticated Heroku customer to:

• Modify usernames or passwords
• Deactivate an account
• Add additional user accounts to your add-on installation
• Take other actions that might modify authentication or authorization.

These functions are handled by Heroku and your SSO integration. When you detect that a user has authenticated via Heroku, you should disable and hide these functions in your dashboard.

Use the Platform API for Partners to fetch lists of users

You can use the Platform API for Partners to obtain owner, team, and collaborator information for an app that has your add-on attached. This API requires that your add-on uses v3 of the Add-on Partner API. See Syncing User Access as an Ecosystem Partner for details.