Granting, changing, and revoking access to resources

This page describes how to grant, change, and revoke access to a resource. You can grant varying levels of access for resources you own to different users by using fine-grained Cloud IAM roles.

You can manage user roles with the GCP Console, the gcloud command-line tool, the REST API, or the client libraries. Using the GCP Console is the easiest method and is covered in the first half of this article. Using programmatic methods for more complex scenarios is covered later on.

If you want to use Cloud IAM with Cloud Identity-Aware Proxy (Cloud IAP) to secure access to your applications, see the Cloud IAP documentation.

Before you begin

• Read about the available Cloud IAM roles.

Using the GCP Console

Using the GCP Console is a quick and easy way to manage user roles. When you grant a user a role, they won't receive an invite email. Their access is updated directly.

Grant access

To add a team member to a project and grant them a Cloud IAM role:

1. Open the IAM page in the GCP Console.

   Open the IAM page

2. Click Select a project, choose a project, and click Open.

3. Click Add.

4. Enter an email address. You can add individuals, service accounts, or Google Groups as members, but every project must have at least one individual as a member.

5. Select a role. Roles give members the appropriate level of permission. We recommend giving the member the least amount of privilege needed. Members with Owner-level permissions are also project owners and can manage all aspects of the project, including shutting it down.

6. Click Save.

To grant a role to a member for more than one project:

1. Open the IAM & Admin Projects page in the GCP Console.

   Open the IAM & Admin Projects page

2. Select all the projects for which you want to grant permissions.

3. Click the Show Info Panel, followed by the Permissions tab.

4. Enter an email address in the Add members field, and select the desired role from the dropdown menu.

5. Click the Add button. The member will be granted the selected role in each of the selected projects.

Revoke access

1. Open the IAM page in the Google Cloud Platform Console.

   Open the IAM page

2. Click Select a project.

3. Select a project and click Open.

4. Locate the member for whom you want to revoke access, and then click the Edit button on the right.

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

Modify access

There is no special procedure for modifying access. Simply follow the steps for granting and revoking access until the user has the desired roles.

Using gcloud, REST API, or client libraries

In some use cases, it's easier to manage access control programmatically rather than by using the GCP Console. You can use the gcloud command-line tool, the REST API, or the client libraries for Cloud IAM. Programmatic methods are particularly useful when making large-scale or automatic updates that would be time-consuming to perform in the GCP Console.

Quick updates using the gcloud command-line tool

If you just want to quickly grant or revoke a single user a role using the command line, use the add-iam-policy-binding and remove-iam-policy-binding commands. Pass in a --role flag for each role you want to add or remove.

To grant a role:

gcloud [GROUP] add-iam-policy-binding [RESOURCE-NAME]
  --member user:[USER-EMAIL] --role [ROLE-ID]

To revoke a role:

gcloud [GROUP] remove-iam-policy-binding [RESOURCE-NAME]
  --member user:[EMAIL] --role [ROLE-ID]

[GROUP] is the gcloud group for the resource you want to grant permissions for, such as projects or organizations. [RESOURCE] is the name of the resource. [EMAIL] is the user to grant the role to. [ROLE-ID] is the ID of the role to grant.

The example below grants the Viewer role to [e-mail] for the project my-project (note that you can only add Owner role to a project through the console)

gcloud projects add-iam-policy-binding my-project
  --member user:[e-mail] --role roles/viewer

Overview of Cloud IAM policy

Access to a resource is managed through an Cloud IAM policy. A policy is a collection of bindings that associate a member, such as a user account or service account, with a role. Policies are represented using JSON or YAML.

Here is an example policy where [e-mail] has been granted the Owner role, and [e-mail] and [e-mail] has been granted the Editor role:

{
  "bindings":[
    {
      "members":[
        "user:[e-mail]"
      ],
      "role":"roles/owner"
    },
    {
      "members":[
        "serviceAccount:[e-mail]",
        "user:[e-mail]"
      ],
      "role":"roles/editor"
    }
  ],
  "etag":"BwUjMhCsNvY=",
  "version":1
}

You update a policy for a resource by using the read-modify-write pattern. This means there are no distinct methods for creating, modifying, or revoking user access. Instead, all modifications are made by:

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 desired members and their role grants.
3. Writing the updated policy by calling setIamPolicy().

It's common to grant permissions for an entire project or organization. However, you can also set policies at a more granular level on a wide range of GCP resources, such as Compute Engine instances or Cloud Storage buckets. For a full list of roles and the lowest resource level you can grant each role at, see Understanding Roles.

Note: In general, any policy changes will take effect within 60 seconds. However, under certain circumstances, it may take up to 7 minutes for such changes to fully propagate across the system.

The sections below demonstrate how to get, modify, and set a policy for a project.

Get policy

GCLOUD COMMAND

Execute the get-iam-policy command:

gcloud projects get-iam-policy [PROJECT] --format [FORMAT] > [FILE-PATH]

[PROJECT] is the name of the project. [FORMAT] is either JSON or YAML. [FILE-PATH] is the path on disk to save the policy.

For example, the following gets the policy for the project my-project in JSON format and saves it to the user's home directory.

gcloud projects get-iam-policy my-project --format json > ~/policy.json

The response will be a policy.

REST API

Call getIamPolicy():

POST https://cloudresourcemanager.googleapis.com/v1/[PROJECT]:getIamPolicy

[PROJECT] is the name of the resource to get policy for, such as projects/my-project.

The response will be a policy.

C#

Before trying this sample, follow the C# setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM C# API reference documentation .

View on GitHub Feedback

using Google.Apis.Auth.OAuth2;
using Google.Apis.CloudResourceManager.v1;
using Google.Apis.CloudResourceManager.v1.Data;

public partial class AccessManager
{
    public static Policy GetPolicy(string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(CloudResourceManagerService.Scope.CloudPlatform);
        var service = new CloudResourceManagerService(
            new CloudResourceManagerService.Initializer
            {
                HttpClientInitializer = credential
            });

        var policy = service.Projects.GetIamPolicy(new GetIamPolicyRequest(),
            projectId).Execute();
        return policy;
    }
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Python API reference documentation .

View on GitHub Feedback

def get_policy(project_id):
    """Gets IAM policy for a project."""

    # pylint: disable=no-member
    policy = service.projects().getIamPolicy(
        resource=project_id, body={}).execute()
    print(policy)
    return policy

Modify policy

Programmatically or using a text editor, modify the policy to grant or revoke roles to given users.

To grant a user an existing role:

GCLOUD COMMAND

The following example grants [e-mail] the Editor using a text editor by appending their email address to the members array under that binding:

{
  "members":[
    "serviceAccount:[e-mail]",
    "user:[e-mail]",
    "user:[e-mail]"
  ],
  "role":"roles/editor"
}

REST API

The following example grants [e-mail] the Editor using a text editor by appending their email address to the members array under that binding:

{
  "members":[
    "serviceAccount:[e-mail]",
    "user:[e-mail]",
    "user:[e-mail]"
  ],
  "role":"roles/editor"
}

C#

Before trying this sample, follow the C# setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM C# API reference documentation .

View on GitHub Feedback

using System.Linq;
using Google.Apis.CloudResourceManager.v1.Data;

public partial class AccessManager
{
    public Policy AddMember(Policy policy, string role, string member)
    {
        var binding = policy.Bindings.First(x => x.Role == role);
        binding.Members.Add(member);
        return policy;
    }
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Python API reference documentation .

View on GitHub Feedback

def modify_policy_add_member(policy, role, member):
    """Adds a new member to a role binding."""
    binding = next(b for b in policy['bindings'] if b['role'] == role)
    binding['members'].append(member)
    print(binding)
    return policy

To add users to a new role that does not already exist, add a new binding.

GCLOUD COMMAND

Using a text editor, add a new binding to the bindings array. The following grants [e-mail] the Reader role:

{
  "members":[
    "user:[e-mail]"
  ],
  "role":"roles/reader"
}

REST API

Using a text editor, add a new binding to the bindings array. The following grants [e-mail] the Reader role:

{
  "members":[
    "user:[e-mail]"
  ],
  "role":"roles/reader"
}

C#

Before trying this sample, follow the C# setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM C# API reference documentation .

View on GitHub Feedback

using System.Collections.Generic;
using Google.Apis.CloudResourceManager.v1.Data;

public partial class AccessManager
{
    public static Policy AddBinding(Policy policy, string role, string member)
    {
        var binding = new Binding
        {
            Role = role,
            Members = new List<string> { member }
        };
        policy.Bindings.Add(binding);
        return policy;
    }
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Python API reference documentation .

View on GitHub Feedback

def modify_policy_add_role(policy, role, member):
    """Adds a new role binding to a policy."""
    binding = {
        'role': role,
        'members': [member]
    }
    policy['bindings'].append(binding)
    print(policy)
    return policy

To revoke access, delete the desired members or bindings entirely. Empty bindings with no members are not allowed.

You can only grant roles related to activated API services. If a service, such as Compute Engine, is not active, you cannot grant roles exclusively related to Compute Engine. For more information, see Enable and disable APIs.

There are some unique constraints when granting permissions on projects, especially when granting the Owner role. See the projects.setIamPolicy()reference documentation for more information.

Set policy

Once you have modified the policy to grant the desired roles, call setIamPolicy() to make the updates.

GCLOUD COMMAND

Execute the set-iam-policy command with the path to the JSON file containing the updated policy:

gcloud projects set-iam-policy [PROJECT] [FILE-PATH]

As with get-iam-policy, [PROJECT] is the name of the project to set policy for. [FILE-PATH] is the path to the file that contains the new policy.

The response will be the updated policy.

REST API

Call setIamPolicy():

POST https://cloudresourcemanager.googleapis.com/v1/[PROJECT]:setIamPolicy

[PROJECT] is the name of the resource to set policy for, such as projects/my-project.

The body of the request should contain the updated IAM policy.

The response will be the updated policy.

C#

View on GitHub Feedback

using Google.Apis.Auth.OAuth2;
using Google.Apis.CloudResourceManager.v1;
using Google.Apis.CloudResourceManager.v1.Data;

public partial class AccessManager
{
    public static Policy SetPolicy(string projectId, Policy policy)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(CloudResourceManagerService.Scope.CloudPlatform);
        var service = new CloudResourceManagerService(
            new CloudResourceManagerService.Initializer
            {
                HttpClientInitializer = credential
            });

        return service.Projects.SetIamPolicy(new SetIamPolicyRequest
        {
            Policy = policy
        }, projectId).Execute();
    }
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Python API reference documentation .

View on GitHub Feedback

def set_policy(project_id, policy):
    """Sets IAM policy for a project."""

    # pylint: disable=no-member
    policy = service.projects().setIamPolicy(
        resource=project_id, body={
            'policy': policy
        }).execute()
    print(policy)
    return policy

To prevent collisions if multiple sources try to update policy simultaneously, the policy contains an etag value. When you call setIamPolicy(), Cloud IAM compares the etag value in the request with the existing etag, and only writes the policy if the values match.

What's next

• Read about the available Cloud IAM roles.
• Learn how to view the roles that you can grant on a particular resource.
• Learn how to grant access to Cloud Pub/Sub resources.
• Learn how to secure your applications with Cloud Identity-Aware Proxy.