Managing an Organization Account
Last updated 29 January 2018
This feature is currently available in Heroku Enterprise
Orgs or Organizations are now known as Enterprise Teams. This article will soon be updates to reflect this change and replace all Org and Organization words with Enterprise Teams.
Organizations allow you to manage access to a shared group of applications across your development team. The development experience remains largely the same, but you now have granular access control and can more efficiently manage your development process.
Once your org is provisioned, you will receive an email from Heroku with the org name, resource limits and a link to your dashboard. This guide outlines how to complete the setup of your org.
When an organization is provisioned it only has one user - the admin user that requested the org. This initial admin can add other users to the org and give them the appropriate access.
Admin and member roles
Users in an organization can be either Admins or members.
An admin user controls membership to the org, can view billing information, and can perform any action on any app owned by the organization. Admin users can:
- Access all apps in the organization
- Add/remove users in the organization
- View resource usage across the organization
- Manage invoices and billing for the organization
- Rename the organization
- Transfer, create, and delete apps in the organization
The admin role is often given to those in the organization that are accountable for spend, development processes and security posture. Admin users can only be added by existing org admins. An org must have at least one admin user. The last administrator in the organization cannot be removed to enforce this.
Member users can only be added by org admins. Assigning a user the member role gives them read-only access to all apps within the organization. They can be granted additional access on a per-app basis. Members can:
- List all apps in the organization
- View admins & members in the organization
- View resources for the organization
- Transfer personal apps into the org
- Create new apps in the org
Users in the member role can view all apps in the organization 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 org. 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.
3rd party collaborators who are not trusted to view all apps in an organization 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 org .i.e. without having to assign them any role in the org. Contract 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 Heroku Organizations, for more information on how members and non-org users can be granted permissions on specific apps.
Users can be managed from the Access tab in your org Dashboard.
You can also manage users using the Heroku CLI. Add a new org member with:
$ heroku members:add email@example.com --org acme-widgets Adding firstname.lastname@example.org as member to organization acme-widgets... done
Add additional admin users using the same command with the
$ heroku members:add email@example.com --org acme-widgets --role admin Adding firstname.lastname@example.org as admin to organization acme-widgets... done
Because of their app-level access, non-org users are a special case and require a different command.
$ heroku access:add email@example.com --app acme-website Adding firstname.lastname@example.org to acme-website as collaborator... done
Two-factor authentication is a Heroku platform security feature. When an 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 organization, admins and other members of the org need visibility into their 2FA status. This helps ensure continuous compliance with security and governance policies.
The Access page of an organization 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.
On seeing users with two-factor authentication disabled, admins of the org may choose to ensure compliance and maintain their security composure by removing those users from the org, changing their role or leaving them with permissions only on specific less-sensitive apps.
Applications become part of an organization in one of two ways – by being transferred into the org or by being created as part of the org.
When starting a new project, org admin and member users can create an app directly within the org. First pick the org from the side bar. Then click the plus sign on the top right corner to create a new app in the org.
Or, from the CLI, specify the org with the
--org flag on the
heroku create command.
$ 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
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 org before it can be managed as part of the org. 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 organization.
You can also use the CLI to transfer apps into an organization:
$ heroku apps:transfer acme-widgets -a deep-spring-4274 Transferring deep-spring-4274 to acme-widgets... done
To transfer multiple apps to an Enterprise Team (Previously known as Org), 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.
Applications can be removed from an org by transferring them to a new owner or by deleting them. Admins can delete or transfer any app in the organization. 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 drop-down at the bottom of the settings page. Apps can be transferred to the user’s own personal account, to another organization in which they are a member or to any org member’s personal account.
Compliance feature: Limiting access to apps via OAuth
Heroku Enterprise Administrators can choose to deny OAuth access to org-owned resources from all non-Heroku products and services. In the settings tab of the org, administrators will find a toggle control where they can switch off third-party OAuth access to the Heroku Platform API. Members of the org can still OAuth with Heroku, but org owned resources will not be accessible.
When third-party OAuth access is disabled, API calls attempted against apps in Orgs 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 Org 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.
At this stage your org 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 org, which describes how to efficiently work within an organization account.
Beyond the basic steps described in this guide, there is also a detailed doc that covers the administration of org users and application access.