Using Single Sign-on (SSO) Services with Heroku, for End Users
Last updated 12 September 2017
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. The Heroku account email domain must be the same as the company email domain.
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.
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
You can authenticate to the Heroku Command Line Interface (CLI) via SSO.
In a terminal window, in the Heroku CLI (Toolbelt), type
heroku login --sso. You will be prompted for your organization name.Your identity provider will open in a browser window. Authenticate as you normally would via your IdP for Heroku’s web interface. When your credentials are accepted, you will be forwarded to Heroku’s web interface, authenticated, and an access token will be displayed.
Paste this access token into the CLI at the “Enter your access token” prompt. You should now be authenticated to the CLI under your SSO identity.
Tip: To skip the organization prompt, you can set it in a single line with the HEROKU_ORGANIZATION variable. Type HEROKU_ORGANIZATION=your_org heroku login --sso where “your_org” is your organization name.
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.