This page describes the general process for granting, changing, and revokingaccess to resources that accept allow policies.

• Manage access to projects, folders, and organizations
• Manage access to service accounts

In Identity and Access Management (IAM), access is granted throughallow policies, alsoknown as IAM policies. An allow policy is attached to aGoogle Cloud resource. Each allow policy contains a collection ofrolebindings that associate one or more principals, such as users or serviceaccounts, with an IAM role. These role bindings grant thespecified roles to the principals, both on the resource that the allow policy isattached to and on all of that resource'sdescendants. Formore information about allow policies, seeUnderstanding allow policies.

This page describes how to manage access to resources using theGoogle Cloud console, the Google Cloud CLI, and the REST API. You can also manageaccess using the Google Cloud client libraries.

Note: You can also use deny policies to prevent principals from using specific IAM permissions. For more information, seeDeny policies.

Before you begin

• Review the list ofresource types that accept allowpolicies.
• Ensure that you have therequired IAMroles.

Required roles

To manage access to a resource, you need permissions to get the resource, and toget and set the allow policy for the resource. These permissions have thefollowing form, whereSERVICE is the name of the servicethat owns the resource andRESOURCE_TYPE is the name ofthe resource type that you want to manage access to:

• SERVICE.RESOURCE_TYPE.get
• SERVICE.RESOURCE_TYPE.getIamPolicy
• SERVICE.RESOURCE_TYPE.setIamPolicy

For example, to manage access to a Compute Engine instance, you need thefollowing permissions:

• compute.instances.get
• compute.instances.getIamPolicy
• compute.instances.setIamPolicy

To gain the required permissions, ask your administrator to grant you apredefined or custom role that includes the permissions. For example, youradministrator could grant you the Security Admin role(roles/iam.securityAdmin), which includes permissions to manage access toalmost all Google Cloud resources.

View current access

The following section shows you how to use the Google Cloud console, thegcloud CLI, and the REST API to view who has access to aresource. You can also view access by using the Google Cloud clientlibraries to get the resource's allow policy.

Note: If you grant access to a user's email alias or a secondary domain, then the values in your allow policy might not match the values that you initially entered. If you grant access to an email alias, then the allow policy displays the user's primary email address. If you grant access to a secondary domain, then the allow policy displays the primary domain.

--format=FORMAT>PATH

Grant or revoke a single IAM role

You can use the Google Cloud console and the gcloud CLI to quicklygrant or revoke a single role for a single principal, without editing theresource's allow policy directly.Common types of principals include GoogleAccounts, service accounts, Google groups, and domains.For a list of all principal types, seePrincipal types.

Note: If theiam.allowedPolicyMemberDomains organization policy constraint is enforced in your organization, then you might not be able to grant roles to newly created groups. If you get afailedPrecondition error when trying to grant a role to a newly created group, wait 24 hours, and then try granting the role again.

In general, policy changes take effect within 2 minutes. However, in some cases, itcan take 7 minutes or more for changes to propagate across the system.

If you need help to identify the most appropriate predefined role, seeFind the right predefined roles.

Grant a single IAM role

To grant a single role to a principal, do the following:

Note: If you grant access to a user's email alias or a secondary domain, then the values in your allow policy might not match the values that you initially entered. If you grant access to an email alias, then the allow policy displays the user's primary email address. If you grant access to a secondary domain, then the allow policy displays the primary domain.

Revoke a single IAM role

To revoke a single role from a principal, do the following:

Grant or revoke multiple IAM roles using Google Cloud console

You can use the Google Cloud console to grant and revoke multiple roles fora single principal:

1. In the Google Cloud console, go to the page listing the resource that youwant to view access to.

   For example, to manage access to a Compute Engine instance, go to theVM instances page.

   Go to VM instances

2. Select the checkbox next to the resource that you want to manage access to.

3. If the info panel is not visible, clickShow info panel.

4. Select the principal whose roles you want to modify:

   • To modify roles for a principal who already has roles on the resource,find a row containing the principal, clickeditEditprincipal in that row, and clickaddAdd anotherrole.

     Note: You cannot edit inherited roles when managing access to aresource. To edit inherited roles, go to the resource where therole was granted.

   • To grant roles to a principal who doesn't have any existing roles on theresource, clickperson_addAdd principal, then enter anidentifier for the principal—for example,my-user@example.com or//iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.

5. Modify the principal's roles:

   • To grant a role to a principal who doesn't have any existing roles on theresource, clickSelect a role, then select a role to grant from thedrop-down list.
   • To grant an additional role to the principal, clickAdd another role,then select a role to grant from the drop-down list.
   • To replace one of the principal's roles with a different role, click theexisting role, then choose a different role to grant from the drop-downlist.
   • To revoke one of the principal's roles, click theDeletedelete button for each role that you want torevoke.

   You can alsoadd a condition to a role,modify a role'scondition, orremove a role'scondition.

6. ClickSave.

Note: If you grant access to a user's email alias or a secondary domain, then the values in your allow policy might not match the values that you initially entered. If you grant access to an email alias, then the allow policy displays the user's primary email address. If you grant access to a secondary domain, then the allow policy displays the primary domain.

Grant or revoke multiple IAM roles programmatically

To make large-scale access changes that involve granting and revoking multipleroles for multiple principals, use theread-modify-write pattern to update theresource's allow policy:

1. Read the current allow policy by callinggetIamPolicy().
2. Edit the allow policy, either by using a text editor or programmatically, toadd or remove any principals or role bindings.
3. Write the updated allow policy by callingsetIamPolicy().

This section shows how to use the gcloud CLI and the REST API toupdate the allow policy. You can also update the allow policy using theGoogle Cloud client libraries.

Note: If theiam.allowedPolicyMemberDomains organization policy constraint is enforced in your organization, then you might not be able to grant roles to newly created groups. If you get afailedPrecondition error when trying to grant a role to a newly created group, wait 24 hours, and then try granting the role again.

In general, policy changes take effect within 2 minutes. However, in some cases, itcan take 7 minutes or more for changes to propagate across the system.

Get the current allow policy

--format=FORMAT>PATH

Modify the allow policy

Programmatically or using a text editor, modify the local copy of yourresource's allow policy to reflect the roles you want to grant or revoke.

To ensure that you do not overwrite other changes, do not edit or remove theallow policy'setag field. Theetag field identifies the current state ofthe allow policy. When youset the updated allow policy,IAM compares theetag value in the request with theexistingetag, and only writes the allow policy if the values match.

To edit the roles that an allow policy grants, you need to edit the rolebindings in the allow policy. Role bindings have the following format:

{"role":"ROLE_NAME","members":["PRINCIPAL_1","PRINCIPAL_2",..."PRINCIPAL_N"],"conditions:"{CONDITIONS}}

The placeholders have the following values:

• ROLE_NAME: The name of the role that you want togrant. Use one of the following formats:

  • Predefined roles:roles/SERVICE.IDENTIFIER
  • Project-level custom roles:projects/PROJECT_ID/roles/IDENTIFIER
  • Organization-level custom roles:organizations/ORG_ID/roles/IDENTIFIER

  For a list of predefined roles, seeUnderstandingroles.

• PRINCIPAL_1,PRINCIPAL_2,...PRINCIPAL_N: Identifiers for the principals thatyou want to grant the role to.

  Principal identifiers usually have the following form:PRINCIPAL-TYPE:ID.For example,user:my-user@example.com orprincipalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.For a full list of the values thatPRINCIPAL can have,seePrincipal identifiers.

  For the principal typeuser, the domain name in the identifier must bea Google Workspace domain or a Cloud Identity domain. To learn how to setup a Cloud Identity domain, see theoverview of Cloud Identity.

• CONDITIONS: Optional. Anyconditionsthat specify when access will be granted.

Grant a role

To grant roles to your principals, modify the role bindings in the allow policy.To learn what roles you can grant, seeUnderstanding roles, orview grantable roles for the resource. If you need help toidentify the most appropriate predefined roles, seeFind the right predefined roles.

Optionally, you can useconditions to grant roles only whencertain requirements are met.

To grant a role that is already included in the allow policy, add the principalto an existing role binding:

{"role":"roles/compute.instanceAdmin","members":["user:kai@example.com"]}

{"role":"roles/compute.instanceAdmin","members":["user:kai@example.com","user:raha@example.com"]}

{"role":"roles/compute.instanceAdmin","members":["user:kai@example.com"]}

{"role":"roles/compute.instanceAdmin","members":["user:kai@example.com","user:raha@example.com"]}

To grant a role that is not yet included in the allow policy, add a new rolebinding:

{"role":"roles/compute.loadBalancerAdmin","members":["user:raha@example.com"]}

{"role":"roles/compute.loadBalancerAdmin","members":["user:raha@example.com"]}

Revoke a role

To revoke a role, remove the principal from the role binding. If there are noother principals in the role binding, remove the entire role binding.

Set the allow policy

After you modify the allow policy to grant and revoke the desired roles, callsetIamPolicy() to make the updates.

Note: If you grant access to a user's email alias or a secondary domain, then the values in your allow policy might not match the values that you initially entered. If you grant access to an email alias, then the allow policy displays the user's primary email address. If you grant access to a secondary domain, then the allow policy displays the primary domain.

What's next

• Learn how tomanage access to projects, folders, andorganizations or how tomanage access to service accounts.
• Find out how tochoose the most appropriate predefined roles.
• Use thePolicy Troubleshooter to understand why a user doesor doesn't have access to a resource or have permission to call an API.
• Discover how toview the roles that you can grant on a particularresource.
• Learn how to make a principal's access conditional withconditional role bindings.