Create Custom Roles for Billing

Cloud Identity and Access Management (IAM) includes fine-grained permissions, which allows you to grant or revoke access to specific actions for individual users. To simplify the process of assigning permissions to users, Cloud IAM roles combine these fine-grained permissions into related groups. Billing has predefined roles, such as Billing Account Administrator or Billing Account Viewer, which should work for most users. But, if they don't fit your needs, custom roles allow 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. After they've been created, you can use the console Billing Overview page to grant custom roles to users, just like with standard predefined roles.

Creating and Managing Custom Roles in the Cloud IAM documentation describes how to configure a custom role, including which permissions are necessary.

Example custom role

Imagine you'd like to give someone the ability to edit cost management features, such as budgets and billing export. The relevant permissions are:

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

With the pre-defined roles, to apply these permissions you would 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 permissions above 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 should be involved, both permissions are necessary.

Just like other Cloud 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 (e.g., account name, currency, open/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.update Billing account
Move account between organizations billing.accounts.removeFromOrganization Billing account (or old organization)
billing.accounts.create New organization
billing.accounts.update 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 costs and usage billing.accounts.getSpendingInformation Billing account

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
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

Action Permission Resource
View budgets list, including month-to-date spend billing.budgets.get Billing account
billing.budgets.list Billing account
Update budget billing.budgets.update Billing account
Create budget billing.budgets.create Billing account

Credits and promotions

Action Permission Resource
View credits list, including original and remaining amount billing.credits.list Billing account
Redeem a promotional code billing.credits.create 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 Cloud Storage bucket or 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
Was this page helpful? Let us know how we did: