Using Single Sign-On (SSO) Services with Heroku, for Administrators
Last updated 27 June 2019
Table of Contents
SSO for Heroku is currently available only to Heroku Enterprise customers.
Heroku easily integrates with your existing identity provider (IdP) to enable single sign-on (SSO) to Heroku using the same credentials and login experience as your other SSO-enabled service providers (such as Slack and Dropbox).
Using SSO, an employee logs in to Heroku using your identity provider’s interface instead of the Heroku login page. The employee’s browser is then redirected to Heroku, authenticated and ready to go. When SSO is enabled, Heroku’s own login mechanism is disabled, meaning that authentication security is shifted to your IdP and coordinated with your other service providers.
Heroku does not notify your employees when SSO is set up, changed, or deactivated for your organization. Make sure to communicate these changes.
When enabling SSO, include the Using Single Sign-on (SSO) Services with Heroku, for End Users article in your rollout communications.
Prerequisites for SSO with Heroku
- Your company’s identity provider (IdP) must support the SAML 2.0 standard.
- You must have administrative permissions on the IdP.
Identity providers with built-in SSO support for Heroku
The following major IdPs provide built-in support for Heroku. To set up SSO for these IdPs, follow the instructions on the vendor’s site.
- Ping Federate
- Ping Identity (administrator login required, then search ‘Heroku’ in application catalog)
- Salesforce Identity
To set up SSO with Microsoft Active Directory, use the SAML 2.0 instructions below.
SSO setup for other SAML 2.0-compliant IdPs
Most SAML 2.0-compliant identity providers require the same information about a service provider to set up SSO. In the case of Heroku, relevant values are available in the Settings tab of the Heroku Enterprise Team you want to enable SSO for:
Note that you must have admin permissions on an Enterprise Team to see this information (and to enable SSO for it).
After configuring SSO on your IdP, you can upload or enter metadata manually. When setup is successful, administrators will see a confirmation dialog, and the the URL of the SSO login for end users is displayed. Make sure to share this URL with your organization.
Providing multiple IdP certificates
To enable zero-downtime with SSO certificate changes, we have now made it possible to add up to three SSO certificates for Enterprise Teams. SAML assertions signed under any one of the non-expired SSO certificates will be accepted, making it possible to seamlessly switch to a new identity provider certificate without downtime.
Heroku also sends email notifications to the admins (users with the
admin permission) of an SSO-enabled Enterprise Team, 30 days, 7 days, and one day before a certificate expire. So, they’ll have the chance to update expiring certificates and avoid users from being locked out.
For improved security, configure your IdP to sign both SAML response and assertion using SHA-256 if the IdP supports it
End user account creation and removal
Creating end user accounts
To add end users, simply create accounts for those users in your IdP. The first time a user logs in to Heroku via the IdP, a Heroku account is created for them via automatic IdP provisioning. The user’s access to the Enterprise Team’s resources and settings depends on the default role to assign new users (specified by an admin in the Enterprise Team’s Settings tab):
The default role for new users is
After the account is provisioned, the end user receives a verification email and needs to click its included acknowledgement link.
Make sure to create an admin user account directly with Heroku (not via the IdP), so you are still able to access Heroku if/when the IdP isn’t working properly.
Create an integrations user account directly with Heroku (not through the IdP) in case you need to set up integrations that require a Heroku API key.
Removing end user accounts
Removing an end user from your IdP prevents the user from logging in to their corresponding Heroku account, but it does not remove the account from Heroku. To insure against possible API access to Enterprise Team resources before API keys time out, make sure also to remove the end user’s account from the Heroku Enterprise Team associated with the IdP.
To remove an end user account from Heroku that was created via automatic IdP provisioning, the Identity Administrator can contact Heroku Support.