Manage access to other resources

This page describes the general process for granting, changing, and revoking access to resources that accept Identity and Access Management (IAM) policies.

In Identity and Access Management (IAM), access is managed through IAM policies. An IAM policy is attached to a Google Cloud resource. Each policy contains a collection of role bindings that associate one or more principals, such as users or service accounts, with an IAM role. These role bindings grant the specified roles to the principals, both on the resource that the policy is attached to and on all of that resource's descendants. For more information about IAM policies, see Understanding policies.

This page describes how to manage access to resources using the Google Cloud Console, the gcloud command-line tool, and the REST API. You can also manage access using the Google Cloud client libraries.

Before you begin

Review the list of resource types that accept IAM policies.

Required permissions

To manage access to a resource, you need permissions to get the resource, and to get and set the IAM policy for the resource. These permissions have the following form, where SERVICE is the name of the service that owns the resource and RESOURCE_TYPE is the name of the resource type that you want to manage access to:

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

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

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

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

View current access

The following section shows you how to use the Cloud Console, the gcloud tool, and the REST API to view who has access to a resource. You can also view access by using the Google Cloud client libraries to get the resource's IAM policy.

Console

  1. In the Cloud Console, go to the page that lists the resource that you want to view access to.

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

    Go to VM instances

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

  3. Ensure that the info panel is visible. If it is not visible, click Show info panel. The info panel's permissions tab lists all principals who have access to the resource.

    If the Show inherited permissions switch is on, the list includes principals with inherited roles; that is, principals whose access comes from roles on parent resources rather than roles on the resource itself. For more information about policy inheritance, see Policy inheritance and the resource hierarchy.

gcloud

To see who has access to your resource, get the IAM policy for the resource. To learn how to interpret IAM policies, see Understanding policies.

To get the IAM policy for the resource, run the get-iam-policy command for the resource.

The format for this command varies depending on the resource type you're managing access to. To find the format for your resource, find the reference for the resource's get-iam-policy command in the Cloud SDK reference. This reference is organized by service, then resource. For example, to get the IAM policy of a Compute Engine, follow the format described in the gcloud compute instances get-iam-policy reference.

Optionally, add the following arguments to the command to specify the format and export the results:

--format=FORMAT > PATH

Provide the following values:

  • FORMAT: The desired format for the policy. Use json or yaml.
  • PATH: The path to a new output file for the policy.

When you run the command, the resource's IAM policy is either printed to the console or exported to the specified file.

REST

To see who has access to your resource, get the resource's IAM policy. To learn how to interpret IAM policies, see Understanding policies.

To get the resource's IAM policy, use the resource's getIamPolicy method.

The HTTP method, URL, and request body depend on the resource that you want to view access to. To find these details, find the API reference for the service that owns the resource, then find the reference for the resource's getIamPolicy method. For example, the HTTP method, URL, and request body for a Compute Engine instance are specified in the instances getIamPolicy reference.

The response for any resource's getIamPolicy method contains the resource's IAM policy.

Grant or revoke a single role

You can use the Cloud Console and the gcloud tool to quickly grant or revoke a single role for a single principal, without editing the resource's IAM policy directly. Common types of principals include Google accounts, service accounts, Google groups, and domains. For a list of all principal types, see Concepts related to identity.

If you need help to identify the most appropriate predefined role, see Choose predefined roles.

Grant a single role

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

Console

  1. In the Cloud Console, go to the page listing the resource that you want to view access to.

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

    Go to VM instances

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

  3. Ensure that the info panel is visible. If it is not visible, click Show info panel.

  4. Select a principal to grant a role to:

    • To grant a role to a principal who already has other roles on the resource, find a row containing the principal's email address, click Edit principal in that row, and click Add another role.

    • To grant a role to a principal who does not already have other roles on the resource, click Add principal, then enter the principal's email address.

  5. Select a role to grant from the drop-down list. For best security practices, choose a role that includes only the permissions that your principal needs.

  6. Optional: Add a condition to the role.

  7. Click Save. The principal is granted the role on the resource.

gcloud

To quickly grant a role to a principal, run the add-iam-policy-binding command.

The format for this command varies depending on the resource type you're managing access to. To find the format for your resource, find the reference for the resource's add-iam-policy-binding command in the Cloud SDK reference. This reference is organized by service, then resource. For example, to grant a principal a role on a Compute Engine instance, follow the format described in the gcloud compute instances add-iam-policy- binding reference.

Revoke a single role

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

Console

  1. In the Cloud Console, go to the page listing the resource that you want to revoke access from.

    For example, to manage access to a Compute Engine instance, go to the VM instances page:

    Go to VM instances

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

  3. Ensure that the info panel is visible. If it is not visible, click Show info panel.

  4. Find the row containing the principal's email address, then click Edit principal in that row.

  5. Click the Delete button for each role you want to revoke, and then click Save.

gcloud

To quickly revoke a role from a principal, run the remove-iam-policy-binding command.

The format for this command varies depending on the resource type you're managing access to. To find the format for your resource, find the reference for the resource's remove-iam-policy-binding command in the Cloud SDK reference. This reference is organized by service, then resource. For example, to grant a principal a role on a Compute Engine instance, follow the format described in the gcloud compute instances remove-iam-policy-binding reference.

Grant or revoke multiple roles

To make large-scale access changes that involve granting and revoking multiple roles, use the read-modify-write pattern to update the resource's IAM policy:

  1. Reading the current policy by calling getIamPolicy().
  2. Editing the returned policy, either by using a text editor or programmatically, to add or remove any principals or role bindings.
  3. Writing the updated policy by calling setIamPolicy().

This section shows how to use the gcloud tool and the REST API to update the policy. You can also update the policy using the Google Cloud client libraries.

Get the current policy

gcloud

To get the IAM policy for the resource, run the get-iam-policy command for the resource.

The format for this command varies depending on the resource type you're managing access to. To find the format for your resource, find the reference for the resource's get-iam-policy command in the Cloud SDK reference. This reference is organized by service, then resource. For example, to get the IAM policy of a Compute Engine, follow the format described in the gcloud compute instances get-iam-policy reference.

Optionally, add the following arguments to the command to specify the format and export the results:

--format=FORMAT > PATH

Provide the following values:

  • FORMAT: The desired format for the policy. Use json or yaml.
  • PATH: The path to a new output file for the policy.

When you run the command, the resource's IAM policy is either printed to the console or exported to the specified file.

REST

To get the resource's IAM policy, use the resource's getIamPolicy method.

The HTTP method, URL, and request body depend on the resource that you want to view access to. To find these details, find the API reference for the service that owns the resource, then find the reference for the resource's getIamPolicy method. For example, the HTTP method, URL, and request body for a Compute Engine instance are specified in the instances getIamPolicy reference.

The response for any resource's getIamPolicy method contains the resource's IAM policy. Save the response in a file of the appropriate type (json or yaml).

Modify the policy

Programmatically or using a text editor, modify the local copy of your resource's policy to reflect the roles you want to grant or revoke to given users.

To ensure that you do not overwrite other policy changes, do not edit or remove the policy's etag field. The etag field identifies the current policy state. When you set the updated policy, IAM compares the etag value in the request with the existing etag, and only writes the policy if the values match.

Grant a role

To grant roles to your principals, modify the role bindings in the policy. To learn what roles you can grant, see Understanding roles, or view grantable roles for the resource. If you need help to identify the most appropriate predefined roles, see Choose predefined roles.

Optionally, you can use conditions to grant roles only when certain requirements are met.

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

gcloud

Edit the returned policy by adding the principal to an existing role binding. Note that this policy change will not take effect until you set the updated policy.

For example, imagine the returned policy contains the following role binding, which grants the Compute Instance Admin role (roles/compute.instanceAdmin) to kai@example.com:

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

To grant that same role to raha@example.com, add raha@example.com to the existing role binding:

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

REST

Edit the returned policy by adding the principal to an existing role binding. Note that this policy change will not take effect until you set the updated policy.

For example, imagine the returned policy contains the following role binding, which grants the Compute Instance Admin role (roles/compute.instanceAdmin) to kai@example.com:

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

To grant that same role to raha@example.com, add raha@example.com to the existing role binding:

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

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

gcloud

Edit the returned policy by adding a new role binding that grants the role to the principal. This policy change will not take effect until you set the updated policy.

For example, to grant the Compute Load Balancer Admin role (roles/compute.loadBalancerAdmin) to raha@example.com, add the following role binding to the bindings array for the policy:

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

REST

Edit the returned policy by adding a new role binding that grants the role to the principal. This policy change will not take effect until you set the updated policy.

For example, to grant the Compute Load Balancer Admin role (roles/compute.loadBalancerAdmin) to raha@example.com, add the following role binding to the bindings array for the policy:

{
  "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 no other principals in the role binding, remove the entire role binding.

gcloud

Revoke a role by editing the JSON or YAML policy returned by the get-iam-policy command. This policy change will not take effect until you set the updated policy.

To revoke a role from a principal, delete the desired principals or bindings from the bindings array for the policy.

REST

Revoke a role by editing the JSON or YAML policy returned by the get-iam-policy command. This policy change will not take effect until you set the updated policy.

To revoke a role from a principal, delete the desired principals or bindings from the bindings array for the policy.

Set the policy

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

gcloud

To set the IAM policy for the resource, run the set-iam-policy command for the resource.

The format for this command varies depending on the resource type you're managing access to. To find the format for your resource, find the reference for the resource's set-iam-policy command in the Cloud SDK reference. This reference is organized by service, then resource. For example, to get the IAM policy of a Compute Engine, follow the format described in the gcloud compute instances set-iam-policy reference.

The response for any resource's set-iam-policy command contains the resource's updated IAM policy.

REST

To set the resource's IAM policy, use the resource's setIamPolicy method .

The HTTP method, URL, and request body depend on the resource that you want to view access to. To find these details, find the API reference for the service that owns the resource, then find the reference for the resource's setIamPolicy method. For example, the HTTP method, URL, and request body for a Compute Engine instance are specified in the instances setIamPolicy reference.

The response for any resource's setIamPolicy method contains the resource's updated IAM policy.

What's next

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Get started for free