Using Single Sign-on (SSO) Services with Heroku, for End Users
Last updated March 18, 2022
Table of Contents
Your Heroku authentication experience under SSO
Once your administrator has enabled single sign on (SSO) for Heroku, you will log into Heroku on your company’s identity provider. This is often the same place you log into other cloud services like Slack and Dropbox. Your company uses the identity provider (IdP) to centralize authentication to any number of cloud or on-premise services, accessing each, usually with a single click.
As a user you only need to enter your username and password one time at the IdP to gain access to all services under the IdP’s control.
Only your identity administrator can add Heroku to the list of service providers available to you under single sign-on. Often these service providers are presented to you in tiles on your main login page.
Email communications about single sign-on will always come from your identity administrator, not Heroku. If you have questions about single sign-on or any particular communication you might receive, contact your company’s identity administrator.
Upgrading your existing Heroku account authentication to SSO
Users that have a Heroku account under their work email will be invited to upgrade their authentication mechanism to SSO at a URL supplied by the company’s identity admin. The upgrade process for the account will change the Heroku login to use the company’s IdP. This gives the company authentication control over the account.
After users have elected to upgrade to SSO, they can no longer log in with personal credentials. They must use SSO. Before upgrading to SSO, users are advised to transfer any personal apps to a different (personal) Heroku account. Users who decline or postpone the upgrade process can re-initiate and join SSO at anytime by navigating to the SSO links.
(Users who cancel the upgrade process will remain un-upgraded and will appear to organization administrators as “not under SSO.”)
There will always be a “personal” area in the upgraded account, but company IT could block access to that Heroku account at any time so the user should understand that “Personal” here is personal in an employee context.
If your account has any long-lived tokens, it is important to understand that these will be invalidated once your account is upgraded to use SSO.
Obtaining a new Heroku account under SSO
When you log into Heroku for the first time via your company identity provider (IdP), a Heroku account is created for that email if one does not already exist. In short, your new Heroku account is created by just-in-time (JIT) provisioning. Heroku trusts the organization’s IdP and creates Heroku accounts if necessary for authenticated users.
You will receive a welcome email from Heroku and you must click the acknowledgment link to activate your account.
Authenticating to the Heroku CLI under SSO
Use the heroku login command to log in to the Heroku CLI under SSO:
$ heroku login
heroku: Press any key to open up the browser to login or q to exit
› Warning: If browser does not open, visit
› https://cli-auth.heroku.com/auth/browser/***
This command opens your web browser to the Heroku login page, where you can select the SSO login option:
After you click the Log in button, the Heroku CLI will automatically log you in:
$ heroku login
heroku: Press any key to open up the browser to login or q to exit
› Warning: If browser does not open, visit
› https://cli-auth.heroku.com/auth/browser/***
heroku: Waiting for login...
Logging in... done
Logged in as me@example.com
You can use the legacy SSO login by setting the environment variable HEROKU_LEGACY_SSO=1. Then, run heroku login to log in directly from the CLI. Note, this is the only method for headless SSO login.
FAQ: My Heroku account under SSO
Q: What if an employee leaves the company? How does the admin access the former employee’s personal apps?
A: The admin can log in as the user and transfer the apps.
Q: If a user upgrades auth to SSO and the IdP itself is disconnected by the admin at a future time, can the user log into their account?
A: Provided you still have access to your company email, you can reset your Heroku password in the normal way, and access your account.
Q: Can I disconnect my account from SSO?
A: No. After you upgrade your authentication and connect to an organization’s IdP, only the IdP admin can disconnect your account from SSO.
Q: How long does my SSO session last on Heroku?
A: An SSO session lasts 8 hours. After 8 hours, you will be prompted to login again.
Q: I already have a Heroku account with permissions on an Enterprise Team or Enterprise Account. Will signing in via SSO change my permissions on that Enterprise Team / Enterprise Account?
A: In most cases, logging in via SSO with an existing Heroku account will not change your permissions on the Enterprise Team or Enterprise Account. The exception to this if you are a collaborator on an Enterprise Team. If a collaborator signs in with SSO to an Enterprise Team they will be given the default permission. The default SSO permission level for an Enterprise Team is specified by an admin in the Enterprise Team’s Settings tab and can be either member, admin, or viewer. For more information on Enterprise Team permissions, see the Heroku Team Permissions and Allowed Actions article. The default SSO permission level for Enterprise Accounts is view and is not configurable. If you already have a Heroku account with permissions on an Enterprise Account, logging in via SSO will not change your permissions in any scenario.
Q: Am I required to enable multi-factor authentication (MFA) when using SSO?
A: Yes, you must enable MFA to ensure compliance with the company’s security and governance policies. When logging in via SSO, you must enable MFA with your identity provider instead of using the platform’s native MFA feature.
