Setting Up Your Heroku Enterprise Team for Identity Federation
Last updated January 27, 2022
Table of Contents
Enterprise Teams were previously known as Heroku Orgs and Heroku Organizations, or simply Orgs and Organizations . This is just a name change and won’t have an impact on any features or settings. We are updating all CLI commands to replace “Org” words also but current Org commands will be supported until the transition is complete.
Heroku Enterprise Teams support identity federation by implementing the SAML standard. With this feature, you can manage access to your Heroku Enterprise Team based on successful authentication with an existing identity management solution where you might be managing your employees’ access to different business systems. In this integration, Heroku plays the role of a service provider and is the consuming entity that requests and receives assertions from the Identity Provider (IdP).
There are 2 parts to the configuration. You will set up your Heroku Enterprise Team with information about your IdP. You also have to set up your IdP to accept requests and respond to Heroku as the service provider relying on the IdP for authentication.
Since the integration is standards based, different IdPs need and provide the same configuration details, but the actual procedures to set and get them differ. In this article, we will explain the configuration using Salesforce Identity as the Identity Provider.
Bootstrapping
When your Heroku Enterprise Team is created, only some users are added as admins. As an admin, you must first log into the Enterprise Team with your Heroku username and password and then configure identity federation. Once you have set up your Enterprise Team for identity federations, users who successfully authenticate through the identity provider are automatically added as members. They can then be granted more permissions on specific apps using app permissions.
Setting up your Heroku Enterprise Team
Required configuration information
Each Enterprise Team is set up as an independent service provider (relying party). You’ll need the following information from your identity provider to set up an Enterprise Team as a relying party.
Login Redirect URL: This is the URL at which your identity provider receives redirects for authentication. When users try to login to the Heroku Enterprise Team or access any resource owned by the Enterprise Team they will be redirected to this URL.
X509 IdP certificate: Heroku uses this certificate to validate the authenticity of assertions sent to it by the IdP. This represents the public key of the key pair that that the IdP uses to sign assertions sent to Heroku.
Getting required configuration from your Salesforce org
Identity federation is based on the SAML 2.0 standard and can be set up with many different identity providers. Salesforce Identity is used only as an example to demonstrate end to end setup.
Existing customers with Salesforce Enterprise Edition and above already have Salesforce Identity as part of their Salesforce org. First, log into your Salesforce org and go to the Admin setup page by clicking Setup on the top menu bar.
Let’s ensure that your Salesforce org is set up to be an identity provider. As pre-requisites, your org must have a custom domain set up in Administer > Domain Management > My Domain and you must have also created a certificate in Administer > Security Controls > Certificate and Key Management.
Now pick Identity Provider under Security Controls. If the identity provider is not enabled, click the Enable Identity Provider button and use the certificate you have already created to set up the identity provider.
By clicking on the Download Metadata button, you can download the IdP metadata as an XML file. This file contains all the configuration details outlined previously. Here is a sample file:
<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://sushi-dev-ed.my.salesforce.com" validUntil="2025-09-09T23:17:44.942Z">
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>MIIEZDCCA0ygAwIBAgIOAU+0UEpTAAAAAECZ07YwDQYJKoZIhvcNAQELBQAwejESMBAGA1UEAwwJc3VzaGlfaWRwMRgwFgYDVQQLDA8wMEQ2MTAwMDAwMDZ0UGQxFzAVBgNVBAoMDlNhbGVzZm9yY2UuY29tMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQswCQYDVQQIDAJDQTEMMAoGA1UEBhMDVVNBMB4XDTE1MDkwOTIyNTMyNFoXDTE3MDkwOTEyMDAwMFowejESMBAGA1UEAwwJc3VzaGlfaWRwMRgwFgYDVQQLDA8wMEQ2MTAwMDAwMDZ0UGQxFzAVBgNVBAoMDlNhbGVzZm9yY2UuY29tMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQswCQYDVQQIDAJDQTEMMAoGA1UEBhMDVVNBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoibkw0wAIvfuG9DZfDCpVrbizZSCrBzdHaCJ4II7/YXjH1M+tWp9L7vcXkegpPRWGlXOrYl+A6k96MSwdLU3d2HGJmrhz+Pur0rq4vpOD3cV4zh9fDtICacL0F9QLMOAsIT0ct1LgEh6usKvmNE1Z5DPfaZAaKAYdYepBDQMAT9ZIm1s4jqMzyQfAQBnVBOxIL6F9GU5Ki40yygRUc0YzbeKEqQR7WxfGACDCNXbm/0drN5Vi6YVtRrGQXIBSyAly72gOowoGBYNHhzsQEROxrKTKqdpjF4JcmMdU4qTI8++zNcJ6YZDdfx6p2+L6wWclv9tlkGsMcpC5yKuV+Pg7wIDAQABo4HnMIHkMB0GA1UdDgQWBBSO7PhFdpH72WQUpMXqmoqziOaClzAPBgNVHRMBAf8EBTADAQH/MIGxBgNVHSMEgakwgaaAFI7s+EV2kfvZZBSkxeqairOI5oKXoX6kfDB6MRIwEAYDVQQDDAlzdXNoaV9pZHAxGDAWBgNVBAsMDzAwRDYxMDAwMDAwNnRQZDEXMBUGA1UECgwOU2FsZXNmb3JjZS5jb20xFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xCzAJBgNVBAgMAkNBMQwwCgYDVQQGEwNVU0GCDgFPtFBKUwAAAABAmdO2MA0GCSqGSIb3DQEBCwUAA4IBAQCALrk9rW+YGd1h6dBBNMP3IwYnmOFHz1e2pVzehu7PZlkZbKmQOvHObj/OCsUxvGiooTMDLUGHZdCKHLoM6+O5MPFGYGPzJuU/+jyD7OSzYsA+k29B6AY2J9eWFifdjlmgLHql2xgL+BFVhINE3xTcn/DXAwm0hj02TWK3xv1ArqX0IH6/s7pGtREfLMQA1Amo7m2SqHo9i0sF5/cinfn+xGJTrzc7PnUwmVcLxx2r5m6+DJ5GnChvwLQoUa33K+OXckiVyEwVPokpb4RGMbugWuBU7AEINrqSl7PzYhvkVZKVztNTrc3MiceIGJCcYpJpB7fviYW+KZoz8T5WlXc3</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sushi-dev-ed.my.salesforce.com/idp/endpoint/HttpPost"/>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://sushi-dev-ed.my.salesforce.com/idp/endpoint/HttpRedirect"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>
The SingleSignOnService element with the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect binding represents the Login Redirect URL.
Remember to use the HTTP-Redirect URL and not the HTTP-POST URL.
You can also download the certificate separately by clicking on the Download Certificate button. This is recommended because the formatting is correctly preserved and you can simply cut and paste the contents of the downloaded file into the Heroku Enterprise Team’s settings page.
Setup
Once you have all the required configuration information, go to the Settings page of your Enterprise Team in the Heroku dashboard. Under the Identity Federation section, click the button to set up configuration. Cut and paste the Login Redirect URL (e.g. https://balansubr-dev-ed.my.salesforce.com/idp/endpoint/HttpRedirect). The IdP certificate in the metadata file you downloaded above needs to be formatted before you can add it to the configuration. Instead, use the certificate file you downloaded; open it in a text editor and cut and paste the contents into the IdP certificate text area.
Once your saved configuration is validated, identity federation is enabled for your Enterprise Team and your Heroku setup is complete. You can now see the specific URL that your users should use to log into your Heroku Enterprise Team through the IdP.
Setting up your identity provider
Required configuration information
Typically identity providers will require the following to register a new service provider. You can construct the required URLs from the Heroku Login URL that is displayed for Heroku Enterprise Teams that are configured/enabled for identity federation.
Start URL: This is the URL at which users will log into the Enterprise Team. This looks like
https://sso.heroku.com/saml/<your Enterprise Team name>/init. This is typically used for IdP driven login scenarios where the user clicks on a link in an internal portal to access a Heroku Enterprise Team.Entity ID: This is the unique identifier that Heroku will send to the IdP when it redirects users to the IdP for authentication. Every Enterprise Team gets its own Entity ID and it takes the form
https://sso.heroku.com/saml/<your Enterprise Team name>ACS (Assertion Consumer Service) URL: This is the URL to which the IdP will post assertions. It takes the form
https://sso.heroku.com/saml/<my Enterprise Team name>/finalizeIssuer: This identifies the entity that is issuing assertions. In Salesforce orgs, this defaults to the domain URL of the Salesforce org. You can leave it unchanged.
Name ID format: This is the format that the service provider (Heroku) and IdP have agreed upon as uniquely representing a user record. Heroku uses
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddresswhich is the email address of the user as recorded in the IdP. Heroku uses the email address to create unique internal user records for users who successfully authenticate with the IdP.Subject Type: This field indicates how the identity of the user will be described in assertions. Heroku requires this to be the username of the user as recorded in the IdP.
Request signature certificate (optional): This is the certificate that the IdP will use to verify authentication requests coming from the service provider. Currently Heroku does not sign authentication requests.
Setting up your Salesforce org as the IdP for your Heroku Enterprise Team
In this section, we will see how you can configure your Heroku Enterprise Team as a relying service provider by setting it up as a connected app. Log into your Salesforce org and go to the Admin setup page by clicking Setup on the top menu bar.
Identity federation is based on the SAML 2.0 standard and can be setup with many different identity providers. Salesforce Identity is used only as an example to demonstrate end to end setup.
Registering your Heroku Enterprise Team as a service provider
Now pick Identity Provider under Security Controls. In the Service Providers section, click the link that lets you create a new connected app to represent a service provider. You can also get to this page by picking Create > Apps under Build on the sidebar and then picking New in the Connected Apps section.
On the New Connected App page, you can enter all pertinent information about the service provider which is the Heroku Enterprise Team in this case. All SAML related configuration goes under the Web App Settings section - ensure that you have checked the Enable SAML checkbox.
In addition to the configuration items described in the previous section, this page also lets you set up the IdP to verify request signatures and encrypt SAML responses. Leave these checkboxes unchecked. Click Save and Heroku is now set up as a service provider. All login requests to the Heroku Enterprise Team will now be redirected to your Salesforce org. Note that if you have multiple Enterprise Teams on Heroku, you will set them up as multiple connected apps because each Heroku Enterprise Team has its own, unique SAML configuration.
Enabling access to the Heroku Enterprise Team on user profiles
You must also add the connected app that you just configured to the profiles you assign to your users. Only users whose assigned profiles are configured to allow access to the connected app representing the Heroku Enterprise Team can successfully authenticate with the IdP to access that Heroku Enterprise Team. Under Manage Users, pick Profiles. Click Edit next to the profile you assign to your developers and other users who should be able to access the Enterprise Team. In the Connected App Access section make sure that the connected app that corresponds to your Enterprise Team is checked. You can enable the same connected app / Heroku Enterprise Team on different profiles.
The Heroku Enterprise Team that you just added as a connected app also shows up on the app launcher. When a logged in user clicks on it, they will be logged into the Heroku dashboard for the Enterprise Team without having to provide their username and password again.
Managing users in an identity federated Enterprise Team
Identity federated Enterprise Teams behave differently in how users are provisioned and managed.
Existing users
You can enable identity federation on your existing Enterprise Teams. You can then share the Heroku login URL for the Enterprise Team with current members and instruct them to thereafter log in through that URL.
The first time existing Enterprise Team users (including admins) log in through the IdP, they are permanently switched over to federated users. They can no longer logon to the Enterprise Team with their Heroku usernames and passwords. This switchover automatically happens for users whose email address provided by the IdP matches the email address they use to log into Heroku directly. Note that they can still log into Heroku using their email address and Heroku password and access their personal apps but they will not have access to the Enterprise Team unless they log in through the IdP.
New members
Once identity federation setup is complete on both Heroku and your IdP, you may distribute this URL to intended users of your Enterprise Team or place it a shared area such as single sign-on portal. Users who successfully log in to the Enterprise Team through the IdP are automatically added as members. If you wish to restrict which users have access to the Enterprise Team, you can use identity provider specific features to enforce that. For example, if you are using Salesforce Identity, you can assign different profiles to different users and include access to the Heroku Enterprise Team (which you set up as a connected app above) only on some profiles.
Mixed mode
By default, a Heroku Enterprise Team set up for identity federation can have members who log on through the IdP and members who log on directly with their Heroku usernames and passwords. This enables you to support users such as temporary contractors who may not have user records in your IdP.
If you wish to allow access only through the IdP, you can remove all non-federated users from your Enterprise Team. The Enterprise Team access page shows you which users are federated. For example, logging in through the IdP and which users are logging in directly using their Heroku usernames and passwords. For the latter set of users, their 2FA status is also presented.
Note that if you remove all non-federated users, in the event of IdP unavailability, nobody will be able to access the Enterprise Team. If you wish to guard against this scenario, you can add a special admin user and leave that user non-federated. If needed, you can then log in directly as this user and disable identity federation for the Enterprise Team until you resolve IdP related issues.
