Create custom roles for Cloud Billing accounts

Identity and Access Management (IAM) includes fine-grained permissions, which lets you grant or revoke access to specific actions for individual users. To simplify the process of assigning permissions to users, IAM roles combine these fine-grained permissions into related groups. Billing has predefined roles, such as Billing Account Administrator or Billing Account Viewer, which work for most users. But, if they don't fit your needs, custom roles let you to grant more specific sets of permissions.

Create a custom role

Custom roles are created on the organization, and then are applied to any billing account in the organization. Creating and Managing Custom Roles in the IAM documentation describes how to configure a custom role, including which permissions are necessary.

After custom roles are created, you can grant custom roles to users just like standard, predefined roles. Learn how to update billing permissions.

Example custom role

Imagine you want to give someone the ability to edit cost management features, such as budget alerts and billing export. The relevant permissions are:

  • billing.budgets.create
  • billing.budgets.update
  • billing.accounts.updateUsageExportSpec

With the predefined roles, to apply these permissions you need to grant the Billing Account Administrator role. But that role also includes permission to delete resource associations, cancel subscriptions, and close the billing account. If you didn't want your users to have those capabilities, you could instead create a custom role with only the three necessary permissions and name it Cost Management Administrator. Then, you could apply that custom role in combination with the Billing Account Viewer role to any users that should have broad cost management permissions but no ability to edit other account properties.

Permission association and inheritance

You can grant billing permissions at the billing account level or at the project level. Most billing permissions belong on the billing account, so roles containing those permissions should be associated with the billing account. Other billing permissions instead belong on a project and need to be associated with the project instead of the billing account.

For example, associating a project with a billing account requires the billing.resourceAssociations.create permission on the billing account and also the resourcemanager.projects.createBillingAssignment permission on the project. This is because project permissions are required for actions where project owners control access, while billing account permissions are required for actions where billing account administrators control access. When both are involved, both permissions are necessary.

Just like other IAM permissions, all billing permissions inherit from higher levels of the billing hierarchy. For example, a user with a role containing billing.accounts.close on an organization can close any billing account within that organization. However, some permissions only apply at higher levels. For example, the billing.accounts.list permission doesn't do anything when applied to an individual billing account, but a user with a role containing billing.accounts.list on an organization can list all billing accounts within that organization.

Billing activities

The following tables describe common billing activities, the permissions required to perform those activities, and the resource that those permissions apply to.

Account management

Action Permission Resource
Get basic account information (for example, account name, currency, or if the account is open or closed) billing.accounts.get Billing account
Upgrade from free trial billing.accounts.update Billing account
Rename account billing.accounts.update Billing account
Change purchase order number billing.accounts.update Billing account
Close account billing.accounts.close Billing account
Reopen closed account billing.accounts.reopen Billing account

Billing account hierarchy

Action Permission Resource
List accounts in organization billing.accounts.list Organization
Create accounts in organization billing.accounts.create Organization
Move account into organization billing.accounts.create Organization
billing.accounts.move Billing account
Move account between organizations billing.accounts.removeFromOrganization Old organization
billing.accounts.create New organization
billing.accounts.move Billing account

Payment information

The payment profile includes customer name, address, and payment method.

Action Permission Resource
View payment profile billing.accounts.getPaymentInfo Billing account
Update payment profile billing.accounts.updatePaymentInfo Billing account
View prices only for the SKUs that have incurred usage billing.accounts.getPricing Billing account
View custom contract prices per SKU for a billing account billing.accounts.getPricing Billing account
View costs and usage for a billing account* billing.accounts.getSpendingInformation Billing account
View costs and usage for a project* billing.resourceCosts.get Project
resourcemanager.projects.get Project

Resource associations

Moving a project between billing accounts requires the same permissions as removing it from the original billing account and associating it with the new one.

Action Permission Resource
View project associations billing.resourceAssociations.list Billing account
resourcemanager.projects.get Project
Associate project with billing account billing.resourceAssociations.create Billing account
resourcemanager.projects.createBillingAssignment Project
Remove project from billing account billing.resourceAssociations.delete Billing account
resourcemanager.projects.deleteBillingAssignment Project

Budgets and spending alerts

Action Permission Resource
View the list of budgets for a Cloud Billing account billing.budgets.get Billing account
billing.budgets.list Billing account
Update a budget that's scoped to a Cloud Billing account billing.budgets.update Billing account
Create a budget for a Cloud Billing account billing.budgets.create Billing account
View the list of budgets that are scoped to a single project resourcemanager.projects.get Project
billing.resourceCosts.get Project
billing.resourcebudgets.read Project
Update a budget that's scoped to a single project resourcemanager.projects.get Project
billing.resourceCosts.get Project
billing.resourcebudgets.read Project
billing.resourcebudgets.write Project
Create a budget that's scoped to a single project resourcemanager.projects.get Project
billing.resourceCosts.get Project
billing.resourcebudgets.read Project
billing.resourcebudgets.write Project

Credits and promotions

Action Permission Resource
View credits list, including original and remaining amount billing.credits.list Billing account
Redeem a promotional code billing.accounts.redeemPromotion Billing account
billing.accounts.update Billing account

Policy

The policy defines which users have access to which resources on a billing account. For information on creating or modifying custom roles, see the Create a Custom Role section, above.

Action Permission Resource
View roles on account, including associated usernames billing.accounts.getIamPolicy Billing account
Give roles to users on account billing.accounts.setIamPolicy Billing account

Export specifications

The export specification defines where to send a copy of all usage-related data, and can contain the name of a BigQuery dataset.

Action Permission Resource
View current export specification (Cloud Storage bucket or BigQuery dataset to export usage data to) billing.accounts.getUsageExportSpec Billing account
Modify export specification billing.accounts.updateUsageExportSpec Billing account