Managing an Enterprise Team
Last updated 14 September 2018
This feature is currently available in Heroku Enterprise
Enterprise Teams were previously known as Heroku Orgs or 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 you might end up using the ones with Org commands until the work is complete.
Enterprise Teams allows you to manage access to a shared group of applications, check resources used by different apps within the Enterprise Team, view and download usage reports, and more . The development experience remains largely the same, but you now have granular access control and can more efficiently manage your development process.
Once your Enterprise Team is provisioned, you will receive an email from Heroku with the name, resource limits and a link to your dashboard. This guide outlines how to complete the setup of your Enterprise Team and make the best use of the main existing tabs/features.
Apps
All applications within the Enterprise Team are listed under the “Apps” tab with their stack image showing up in the right column. Pipelines, with the icon of multiple apps, don’t have a stack image displayed. Applications become part of an Enterprise Team in one of two ways – by being transferred into the Enterprise Team or by being created as part of the Enterprise Team.
Creating apps
When starting a new project, Enterprise Team users with “admin” and “member” permissions can create an app directly within the Enterprise Team. First pick the Enterprise Team from the main menu. Then click the new button on the top right corner to create a new app.
Or, from the CLI, specify the Enterprise Team name with the --org flag on the heroku create command. If you don’t provide an app name, like the following example, a random one gets generated. Heroku’s naming style is <adjective>-<noun>-<4 digit number>, with the adjectives and nouns drawn from a list of brand-friendly words.
$ heroku create --org acme-widgets
Creating gentle-garden-8862 in organization acme-widgets... done, stack is cedar-14
https://gentle-garden-8862.herokuapp.com/ | https://git.heroku.com/gentle-garden-8862.git
To specify the app name run the following:
$ heroku create --org acme-widgets --app apple
Creating apple... done
https://apple.herokuapp.com/ | https://git.heroku.com/apple.git
Transferring apps
It is common for existing development teams to have several apps already in development under each developer’s personal account or even a shared personal account. The owner of these apps must transfer in their app to the Enterprise Team before it can be managed as part of the Enterprise Team. Otherwise the individual app owners will continue to be billed for them using their personal billing details.
In Dashboard, to transfer an application, the current app owner must first go to the Settings tab of the application, scroll down to the “Transfer Ownership” section and select the Enterprise Team.
You can also use the CLI to transfer apps into an Enterprise Team:
$ heroku apps:transfer acme-widgets -a deep-spring-4274
Transferring deep-spring-4274 to acme-widgets... done
Bulk Transfer Apps
To transfer multiple apps to an Enterprise Team, select the Enterprise Team you want to transfer apps to, then the Settings tab. Now select the “Transfer Apps” button in front of Bulk App Transfer, select your apps and transfer them to the new Enterprise Team.
Remove apps
Applications can be removed from an Enterprise Team by transferring them to a new owner or by deleting them. Admins can delete or transfer any app. Members can delete or transfer apps on which they have the manage permission.
To transfer an application, select the app to transfer from the Apps page, then go to the Settings pane and use the transfer ownership drop-down at the bottom of the settings page. Apps can be transferred to the user’s own personal account, to another Enterprise Team in which they are a member of, to a Heroku Team, or to any Enterprise Team member’s personal account.
To Delete the app, select the delete app button and confirm.
Compliance feature: Limiting access to apps via OAuth
Heroku Enterprise Administrators can choose to deny OAuth access to Enterprise-Team-owned resources from all non-Heroku products and services. In the settings tab of the Enterprise Team, administrators will find a toggle control where they can switch off third-party OAuth access to the Heroku Platform API. Members of the Enterprise Team can still OAuth with Heroku, but resources owned by the Enterprise Team will not be accessible.
When third-party OAuth access is disabled, API calls attempted against apps in Enterprise Teams will return a failure. Note that previously configured services setup with an app in a personal account or Heroku Team may break if that app is then transferred to an Enterprise Team that has third-party OAuth access disabled.
Note also that some third-party add-ons make use of OAuth and could be blocked regardless of Add-on Controls settings.
Spaces
If you have Heroku Private Spaces, they will show up under this tab. You can create a space by selecting the “Create a Space” button. Please note that each Heroku Private Space costs $1000 in Add-on Credits/month (pro-rated to the second).
Access
All users in an Enterprise Team are listed under the Access tab.
When an Enterprise Team is provisioned it only has one user - the admin user that requested the team. This initial admin can add other users to the team and give them the appropriate access.
Admin, member, and viewer roles
Users in an Enterprise Team can be Admins, members, or viewers.
An admin user controls membership to the Enterprise Team, can view billing information, and can perform any action on any app owned by the team. Admin users can:
- Access all apps in the Enterprise Team
- Add/remove users in the Enterprise Team
- View resource usage across the Enterprise Team
- Manage invoices and billing for the Enterprise Team
- Rename the Enterprise Team
- Transfer, create, and delete apps in the Enterprise Team
The admin role is often given to those accountable for spend, development processes and security posture. Admin users can only be added by existing admins. An Enterprise Team must have at least one admin user. The last administrator in an Enterprise Team cannot be removed to enforce this rule.
Member users can only be added by Enterprise Team admins. Assigning a user the member role gives them read-only access to all apps within the Enterprise Team. They can be granted additional access on a per-app basis. Members can:
- List all apps in the Enterprise Team
- View admins & members in the Enterprise Team
- View resources for the Enterprise Team
- Transfer personal apps into the Enterprise Team
- Create new apps in the Enterprise Team
Users in the member role can view all apps and see basic details about each app. By default, they cannot perform any other operations on the app. They have to be granted additional permissions on a per app basis to be able to perform development and operational tasks on specific apps. Members who have the manage permission on an app (including admins) can grant other members additional permissions.
The member role allows users to create apps within, and transfer apps to, an Enterprise Team. Members automatically get all permissions on the apps they create and can grant other members specific permissions on their apps. The member role is commonly assigned to the in-house developers working on your applications.
Viewer is a limited role that enables users to view apps and pipelines, spaces, users (Access Tab) and resources.
3rd party collaborators who are not trusted to view all apps in the Enterprise Team can be granted permissions on specific apps. Members can do this on the apps they manage without having to add these external developers to the team .i.e. without having to assign them any role in the Enterprise Team. Contractor developers assigned to a specific project are a good example of where this capability is useful - they can be granted access to only the apps that are part of that project.
Please see Using App Permissions in Enterprise Teams for more information on how members and non team members can be granted permissions on specific apps, and the Enterprise Teams Permissions & Allowed Actions article for detailed capabilities per role.
Adding or deleting users or editing permissions
Users can be added and managed from the Access tab in your Enterprise Team Dashboard. To edit permissions or remove a user, select the small pen in the far right column. To add a new user, click the “Add User” button.
You can also manage users using the Heroku CLI. Add a new Enterprise Team member with:
$ heroku members:add joe@acme.com --org acme-widgets
Adding joe@acme.com as member to organization acme-widgets... done
Add additional admin users using the same command with the --role flag:
$ heroku members:add joe@acme.com --org acme-widgets --role admin
Adding joe@acme.com as admin to organization acme-widgets... done
Because of their app-level access, non-enterprise-team users (collaborators) are a special case and require a different command. In this example we are adding “jill@creativeinc.com” as a collaborator to the “acme-website” app with only “view” permission. “View” is one of of the four app permissions. Other three are “deploy”, “manage” and “operate”.
$ heroku access:add jill@creativeinc.com --app acme-website --permissions view
Adding jill@creativeinc.com to acme-website as collaborator... done
Removing yourself from an Enterprise Team
An enterprise team user or collaborator can remove themselves from the enterprise team. The method of removal depends the role. If you are an “admin”, “member” or “viewer” you can remove yourself via the “Access” tab of the Enterprise Team or from the CLI:
You can not leave an Enterprise Team if you are the last remaining admin. Another user should be assigned the “admin” role before you can remove yourself.
The following examples assume that your Enterprise Team is named example-team and your email address is email@example.com.
$ heroku members:remove --team example-team email@example.com
If you are a collaborator on any apps owned by a team, you must remove yourself from each app to be disassociated from the team. Since collaborators are not technically a member of the Enterprise Team, they can’t remove themselves via the access tab.
The following example assumes that you are a collaborator on two apps, each named my-app-1 and my-app-2.
$ heroku access:remove -a my-app-1 email@example.com
$ heroku access:remove -a my-app-2 email@example.com
2FA and SSO Status
Two-factor authentication is a Heroku platform security feature. When a user enables 2FA on their account, they are required to log on with a verification code in addition to their username and password, for additional security.
Users can enable and disable 2FA on their individual accounts. When these users are part of an Enterprise Team, admins and other members need visibility into their 2FA status. This helps ensure continuous compliance with security and governance policies.
The Access page of an Enterprise Team highlights users who have either never enabled or have currently disabled two-factor authentication for their Heroku accounts. The status is updated as soon as it changes.
SSO column shows if a user is using SSO or not. It also indicates the identity provider being used - the Enterprise Team identity provider or a different (Enterprise Account) identity provider.
On seeing users with two-factor authentication and/or SSO disabled, admins of the Enterprise Team may choose to ensure compliance and maintain their security composure by removing those users from the team, changing their role or leaving them with permissions only on specific less-sensitive apps.
You can get more details about each 2FA or SSO status by scrolling over the enabled/disabled status displayed for each user.
Resources
Lists all resources used by all applications within the Enterprise Team.
Settings
Use the settings tab to:
- Rename your Enterprise Team
- Set up SSO
- Change the default from “member”. After this change all new users added to the Enterprise Team will have the new default permissions
- Control which add-ons can be used with apps in the Enterprise Team
- Move multiple apps into your Enterprise Team using Bulk app transfer
When transferring apps that are using free dynos from a Personal to an Enterprise Team account, those dynos will automatically be upgraded to Hobby level as Enterprise Teams cannot use free dyno hours.
- Limit access to apps via OAuth as explained under “Compliance feature: Limiting access to apps via OAuth” section above
- Create a support ticket to have your Enterprise Team deleted
Usage
Usage tab shows all active licenses in the Enterprise Team, current usage, and usage history which lists dyno units and add-on service costs.
Only users with the admin permission can access the settings and usage tabs.
Next steps
At this stage your Enterprise Team should be populated with an initial list of applications and users, and your development team should be able to deploy and manage the apps using the standard Heroku workflow and tools. Your developers will benefit from reading the guide on developing apps within an Enterprise Team, which describes how to efficiently work within an Enterprise Team.
Beyond the basic steps described in this guide, there is also a detailed doc that covers the administration of Enterprise Team users and application access.