Using Cloud IAM permissions

This page describes how to control access to buckets and objects using Cloud Identity and Access Management (Cloud IAM) permissions. Cloud IAM allows you to control who has access to your buckets and objects. To learn more about Cloud IAM for Cloud Storage, see the Overview of Cloud IAM.

To learn about other ways to control access to buckets and objects, read Overview of Access Control. To learn about controlling access to individual objects in your buckets, see Access Control Lists.

Note: Cloud IAM policies cannot be managed using the XML API. Cloud IAM policies containing Cloud IAM Conditions^BETA cannot be managed using client libraries.

Using Cloud IAM with buckets

The following sections show how to complete basic Cloud IAM tasks on buckets.

Adding a member to a bucket-level policy

For a list of roles associated with Cloud Storage, see Cloud IAM Roles. For information on entities to which you grant Cloud IAM roles, see Member Types.

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. Click the Bucket overflow menu () associated with the bucket to which you want to grant a member a role.

3. Choose Edit bucket permissions.

4. In the Add members field, enter one or more identities that need access to your bucket.

   

5. Select a role (or roles) from the Select a role drop-down menu. The roles you select appear in the pane with a short description of the permissions they grant.

6. Click Add.

gsutil

Use the gsutil iam ch command:

gsutil iam ch [MEMBER_TYPE]:[MEMBER_NAME]:[IAM_ROLE] gs://[BUCKET_NAME]

Where:

• [MEMBER_TYPE] is the type of member to which you are granting bucket access. For example, user.
• [MEMBER_NAME] is the name of the member to which you are granting bucket access. For example, [e-mail].
• [IAM_ROLE] is the IAM role you are granting to the member. For example, roles/storage.objectCreator.
• [BUCKET_NAME] is the name of the bucket you are granting the member access to. For example, my-bucket.

For more examples of how to format [MEMBER_TYPE]:[MEMBER_NAME]:[IAM_ROLE], see the gsutil iam ch reference page.

Note: The gsutil iam ch command does not work with policies that contain conditions. To modify a policy that has conditions, use gsutil iam get to retrieve the policy for the relevant bucket, edit it locally, and then use gsutil iam set to re-apply it to the bucket.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation .

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string role,
   std::string member) {
  auto policy = client.GetNativeBucketIamPolicy(bucket_name);

  if (!policy) {
    throw std::runtime_error(policy.status().message());
  }

  for (auto& binding : policy->bindings()) {
    if (binding.role() != role) {
      continue;
    }
    auto& members = binding.members();
    if (std::find(members.begin(), members.end(), member) == members.end()) {
      members.emplace_back(member);
    }
  }

  auto updated_policy = client.SetNativeBucketIamPolicy(bucket_name, *policy);

  if (!updated_policy) {
    throw std::runtime_error(updated_policy.status().message());
  }

  std::cout << "Updated IAM policy bucket " << bucket_name
            << ". The new policy is " << *updated_policy << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation .

View on GitHub Feedback

private void AddBucketIamMember(string bucketName,
    string role, string member)
{
    var storage = StorageClient.Create();
    var policy = storage.GetBucketIamPolicy(bucketName);
    Policy.BindingsData bindingToAdd = new Policy.BindingsData();
    bindingToAdd.Role = role;
    string[] members = { member };
    bindingToAdd.Members = members;
    policy.Bindings.Add(bindingToAdd);
    storage.SetBucketIamPolicy(bucketName, policy);
    Console.WriteLine($"Added {member} with role {role} "
        + $"to {bucketName}");
}

Go

For more information, see the Cloud Storage Go API reference documentation .

View on GitHub Feedback

bucket := c.Bucket(bucketName)
policy, err := bucket.IAM().Policy(ctx)
if err != nil {
	return err
}
// Other valid prefixes are "serviceAccount:", "user:"
// See the documentation for more values.
// https://cloud.google.com/storage/docs/access-control/iam
policy.Add("group:[e-mail]", "roles/storage.objectViewer")
if err := bucket.IAM().SetPolicy(ctx, policy); err != nil {
	return err
}
// NOTE: It may be necessary to retry this operation if IAM policies are
// being modified concurrently. SetPolicy will return an error if the policy
// was modified since it was retrieved.

Java

For more information, see the Cloud Storage Java API reference documentation .

View on GitHub Feedback

// Initialize a Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// Get IAM Policy for a bucket
Policy policy = storage.getIamPolicy(bucketName);

// Add identity to Bucket-level IAM role
Policy updatedPolicy =
    storage.setIamPolicy(bucketName, policy.toBuilder().addIdentity(role, identity).build());

if (updatedPolicy.getBindings().get(role).contains(identity)) {
  System.out.printf("Added %s with role %s to %s\n", identity, role, bucketName);
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation .

View on GitHub Feedback

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const roleName = 'Role to grant, e.g. roles/storage.objectViewer';
// const members = [
//   'user:[e-mail]',    // Example members to grant
//   'group:[e-mail]', // the new role to
// ];

// Creates a client
const storage = new Storage();

// Get a reference to a Google Cloud Storage bucket
const bucket = storage.bucket(bucketName);

// Gets and updates the bucket's IAM policy
const [policy] = await bucket.iam.getPolicy();

// Adds the new roles to the bucket's IAM policy
policy.bindings.push({
  role: roleName,
  members: members,
});

// Updates the bucket's IAM policy
await bucket.iam.setPolicy(policy);

console.log(
  `Added the following member(s) with role ${roleName} to ${bucketName}:`
);

members.forEach(member => {
  console.log(`  ${member}`);
});

PHP

For more information, see the Cloud Storage PHP API reference documentation .

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Adds a new member / role IAM pair to a given Cloud Storage bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $role the role you want to add a given member to.
 * @param string $member the member you want to give the new role for the Cloud
 * Storage bucket.
 *
 * @return void
 */
function add_bucket_iam_member($bucketName, $role, $member)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $policy = $bucket->iam()->policy();

    $policy['bindings'][] = [
        'role' => $role,
        'members' => [$member]
    ];

    $bucket->iam()->setPolicy($policy);

    printf('User %s added to role %s for bucket %s' . PHP_EOL, $member, $role, $bucketName);
}

Python

For more information, see the Cloud Storage Python API reference documentation .

View on GitHub Feedback

from google.cloud import storage


def add_bucket_iam_member(bucket_name, role, member):
    """Add a new member to an IAM Policy"""
    # bucket_name = "your-bucket-name"
    # role = "IAM role, e.g. roles/storage.objectViewer"
    # member = "IAM identity, e.g. user: [e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    policy = bucket.get_iam_policy()

    policy[role].add(member)

    bucket.set_iam_policy(policy)

    print("Added {} with role {} to {}.".format(member, role, bucket_name))

Ruby

For more information, see the Cloud Storage Ruby API reference documentation .

View on GitHub Feedback

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Your Google Cloud Storage bucket name"
# role        = "Bucket-level IAM role"
# member      = "Bucket-level IAM member"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project_id: project_id
bucket = storage.bucket bucket_name

bucket.policy do |policy|
  policy.add role, member
end

puts "Added #{member} with role #{role} to #{bucket_name}"

JSON

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .json file that contains the following information:

   {
     "bindings":[
       {
         "role": "[IAM_ROLE]",
         "members":[
           "[MEMBER_NAME]"
         ]
       }
     ]
   }

   Where:

   • [IAM_ROLE] is the IAM role you are granting the member. For example, roles/storage.objectCreator.

   • [MEMBER_NAME] is the name of the member to which you are granting bucket access. For example, [e-mail].

     For more examples of how to format [MEMBER_NAME], see the members section here.

3. Use cURL to call the JSON API with a PUT setIamPolicy request:

   curl -X PUT --data-binary @[JSON_FILE_NAME].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/iam"

   Where:

   • [JSON_FILE_NAME] is the name of the file you created in Step 2.
   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the bucket to which you want to give the member access. For example, my-bucket.

Note: You should set the minimum permission possible that gives the member the required access. For example, if the team member only needs to read objects stored in a bucket, select the Storage Object Viewer role. Similarly, if the team member needs full control of objects in the bucket (but not control of the bucket itself), select Storage Object Admin.

Viewing the Cloud IAM policy for a bucket

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. Click the Bucket overflow menu () associated with the bucket to which you want to view role members.

3. Choose Edit bucket permissions.

4. Expand the desired role to view the members who have been assigned to it.

5. (Optional) Use the search bar to filter your results by role or member.

   If you search by member, your results display each role that the member is assigned to.

gsutil

Use the gsutil iam get command:

gsutil iam get gs://[BUCKET_NAME]

Where [BUCKET_NAME] is the name of the bucket whose Cloud IAM policy you want to view. For example, my-bucket.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation .

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name) {
  auto policy = client.GetNativeBucketIamPolicy(bucket_name);

  if (!policy) {
    throw std::runtime_error(policy.status().message());
  }

  std::cout << "The IAM policy for bucket " << bucket_name << " is "
            << *policy << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation .

View on GitHub Feedback

private void ViewBucketIamMembers(string bucketName)
{
    var storage = StorageClient.Create();
    var policy = storage.GetBucketIamPolicy(bucketName);
    foreach (var binding in policy.Bindings)
    {
        Console.WriteLine($"  Role: {binding.Role}");
        Console.WriteLine("  Members:");
        foreach (var member in binding.Members)
        {
            Console.WriteLine($"    {member}");
        }
    }
}

Go

For more information, see the Cloud Storage Go API reference documentation .

View on GitHub Feedback

policy, err := c.Bucket(bucketName).IAM().Policy(ctx)
if err != nil {
	return nil, err
}
for _, role := range policy.Roles() {
	log.Printf("%q: %q", role, policy.Members(role))
}

Java

For more information, see the Cloud Storage Java API reference documentation .

View on GitHub Feedback

// Initialize a Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// Get IAM Policy for a bucket
Policy policy = storage.getIamPolicy(bucketName);

// Print Roles and its identities
Map<Role, Set<Identity>> policyBindings = policy.getBindings();
for (Map.Entry<Role, Set<Identity>> entry : policyBindings.entrySet()) {
  System.out.printf("Role: %s Identities: %s\n", entry.getKey(), entry.getValue());
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation .

View on GitHub Feedback

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Gets and displays the bucket's IAM policy
const results = await storage.bucket(bucketName).iam.getPolicy();

const policy = results[0].bindings;

// Displays the roles in the bucket's IAM policy
console.log(`Roles for bucket ${bucketName}:`);
policy.forEach(role => {
  console.log(`  Role: ${role.role}`);
  console.log(`  Members:`);

  const members = role.members;
  members.forEach(member => {
    console.log(`    ${member}`);
  });
});

PHP

For more information, see the Cloud Storage PHP API reference documentation .

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * View Bucket IAM members for a given Cloud Storage bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 *
 * @return void
 */
function view_bucket_iam_members($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $policy = $bucket->iam()->policy();

    printf('Printing Bucket IAM members for Bucket: %s' . PHP_EOL, $bucketName);
    printf(PHP_EOL);

    foreach ($policy['bindings'] as $binding) {
        printf('Role: %s' . PHP_EOL, $binding['role']);
        printf('Members:' . PHP_EOL);
        foreach ($binding['members'] as $member) {
            printf('  %s' . PHP_EOL, $member);
        }
        printf(PHP_EOL);
    }
}

Python

For more information, see the Cloud Storage Python API reference documentation .

View on GitHub Feedback

from google.cloud import storage


def view_bucket_iam_members(bucket_name):
    """View IAM Policy for a bucket"""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    policy = bucket.get_iam_policy()

    for role in policy:
        members = policy[role]
        print("Role: {}, Members: {}".format(role, members))

Ruby

For more information, see the Cloud Storage Ruby API reference documentation .

View on GitHub Feedback

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Your Google Cloud Storage bucket name"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project_id: project_id
bucket = storage.bucket bucket_name

policy = bucket.policy

policy.roles.each do |role, members|
  puts "Role: #{role} Members: #{members}"
end

JSON

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the JSON API with a GET getIamPolicy request:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/iam"

   Where:

   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the bucket whose Cloud IAM policy you want to view. For example, my-bucket.

Note: Some roles may not appear in the bucket permissions window. If you assign roles at the project level, they do not appear in the bucket permission window, even when users with that role have access to your bucket. To view these project-level permissions, go to the IAM & Admin screen.

Removing a member from a bucket-level policy

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. Click the Bucket overflow menu () associated with the bucket from which you want to remove a member's role.

3. Choose Edit bucket permissions.

4. Expand the role that contains the member you are removing.

5. Hover over the member and click on the trash icon that appears.

   

6. In the overlay window that appears, click Remove.

gsutil

Use the gsutil iam ch command with a -d flag:

gsutil iam ch -d [MEMBER_TYPE]:[MEMBER_NAME] gs://[BUCKET_NAME]

Where:

• [MEMBER_TYPE] is the type of the member you are removing from the policy. For example, user.
• [MEMBER_NAME] is the name of the member you are removing from the policy. For example, [e-mail].
• [BUCKET_NAME] is the name of the bucket from which you are removing member access. For example, my-bucket.

For more examples of how to format [MEMBER_TYPE]:[MEMBER_NAME], see the gsutil iam ch reference page.

Note: The gsutil iam ch command does not work with policies that contain conditions. To modify a policy that has conditions, use gsutil iam get to retrieve the policy for the relevant bucket, edit it locally, and then use gsutil iam set to re-apply it to the bucket.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation .

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string role,
   std::string member) {
  auto policy = client.GetNativeBucketIamPolicy(bucket_name);
  if (!policy) {
    throw std::runtime_error(policy.status().message());
  }

  std::vector<google::cloud::storage::NativeIamBinding> updated_bindings;
  for (auto& binding : policy->bindings()) {
    auto& members = binding.members();
    if (binding.role() == role) {
      members.erase(std::remove(members.begin(), members.end(), member),
                    members.end());
    }
    if (!members.empty()) {
      updated_bindings.emplace_back(std::move(binding));
    }
  }
  policy->bindings() = std::move(updated_bindings);

  auto updated_policy = client.SetNativeBucketIamPolicy(bucket_name, *policy);

  if (!updated_policy) {
    throw std::runtime_error(updated_policy.status().message());
  }

  std::cout << "Updated IAM policy bucket " << bucket_name
            << ". The new policy is " << *updated_policy << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation .

View on GitHub Feedback

private void RemoveBucketIamMember(string bucketName,
    string role, string member)
{
    var storage = StorageClient.Create();
    var policy = storage.GetBucketIamPolicy(bucketName);
    policy.Bindings.ToList().ForEach(response =>
    {
        if (response.Role == role)
        {
            // Remove the role/member combo from the IAM policy.
            response.Members = response.Members
                .Where(m => m != member).ToList();
            // Remove role if it contains no members.
            if (response.Members.Count == 0)
            {
                policy.Bindings.Remove(response);
            }
        }
    });
    // Set the modified IAM policy to be the current IAM policy.
    storage.SetBucketIamPolicy(bucketName, policy);
    Console.WriteLine($"Removed {member} with role {role} "
        + $"to {bucketName}");
}

Go

For more information, see the Cloud Storage Go API reference documentation .

View on GitHub Feedback

bucket := c.Bucket(bucketName)
policy, err := bucket.IAM().Policy(ctx)
if err != nil {
	return err
}
// Other valid prefixes are "serviceAccount:", "user:"
// See the documentation for more values.
// https://cloud.google.com/storage/docs/access-control/iam
policy.Remove("group:[e-mail]", "roles/storage.objectViewer")
if err := bucket.IAM().SetPolicy(ctx, policy); err != nil {
	return err
}
// NOTE: It may be necessary to retry this operation if IAM policies are
// being modified concurrently. SetPolicy will return an error if the policy
// was modified since it was retrieved.

Java

For more information, see the Cloud Storage Java API reference documentation .

View on GitHub Feedback

// Initialize a Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// Get IAM Policy for a bucket
Policy policy = storage.getIamPolicy(bucketName);

// Remove an identity from a Bucket-level IAM role
Policy updatedPolicy =
    storage.setIamPolicy(bucketName, policy.toBuilder().removeIdentity(role, identity).build());

if (updatedPolicy.getBindings().get(role) == null
    || !updatedPolicy.getBindings().get(role).contains(identity)) {
  System.out.printf("Removed %s with role %s from %s\n", identity, role, bucketName);
}

Node.js

For more information, see the Cloud Storage Node.js API reference documentation .

View on GitHub Feedback

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const roleName = 'Role to grant, e.g. roles/storage.objectViewer';
// const members = [
//   'user:[e-mail]',    // Example members to grant
//   'group:[e-mail]', // the new role to
// ];

// Creates a client
const storage = new Storage();

// Get a reference to a Google Cloud Storage bucket
const bucket = storage.bucket(bucketName);

// Gets and updates the bucket's IAM policy
const [policy] = await bucket.iam.getPolicy();

// Finds and updates the appropriate role-member group
const index = policy.bindings.findIndex(role => role.role === roleName);
const role = policy.bindings[index];
if (role) {
  role.members = role.members.filter(
    member => members.indexOf(member) === -1
  );

  // Updates the policy object with the new (or empty) role-member group
  if (role.members.length === 0) {
    policy.bindings.splice(index, 1);
  } else {
    policy.bindings.index = role;
  }

  // Updates the bucket's IAM policy
  await bucket.iam.setPolicy(policy);
} else {
  // No matching role-member group(s) were found
  throw new Error('No matching role-member group(s) found.');
}

console.log(
  `Removed the following member(s) with role ${roleName} from ${bucketName}:`
);
members.forEach(member => {
  console.log(`  ${member}`);
});

PHP

For more information, see the Cloud Storage PHP API reference documentation .

View on GitHub Feedback

use Google\Cloud\Core\Iam\PolicyBuilder;
use Google\Cloud\Storage\StorageClient;

/**
 * Removes a member / role IAM pair from a given Cloud Storage bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $role the role you want to remove a given member from.
 * @param string $member the member you want to remove from the given role.
 *
 * @return void
 */
function remove_bucket_iam_member($bucketName, $role, $member)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $policy = $bucket->iam()->policy();
    $policyBuilder = new PolicyBuilder($policy);
    $policyBuilder->removeBinding($role, [$member]);

    $bucket->iam()->setPolicy($policyBuilder->result());
    printf('User %s removed from role %s for bucket %s' . PHP_EOL, $member, $role, $bucketName);
}

Python

For more information, see the Cloud Storage Python API reference documentation .

View on GitHub Feedback

from google.cloud import storage


def remove_bucket_iam_member(bucket_name, role, member):
    """Remove member from bucket IAM Policy"""
    # bucket_name = "your-bucket-name"
    # role = "IAM role, e.g. roles/storage.objectViewer"
    # member = "IAM identity, e.g. user: [e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    policy = bucket.get_iam_policy()

    policy[role].discard(member)

    bucket.set_iam_policy(policy)

    print("Removed {} with role {} from {}.".format(member, role, bucket_name))

Ruby

For more information, see the Cloud Storage Ruby API reference documentation .

View on GitHub Feedback

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Your Google Cloud Storage bucket name"
# role        = "Bucket-level IAM role"
# member      = "Bucket-level IAM member"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project_id: project_id
bucket = storage.bucket bucket_name

bucket.policy do |policy|
  policy.remove role, member
end

puts "Removed #{member} with role #{role} from #{bucket_name}"

JSON

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Get the existing policy applied to your project. To do so, use cURL to call the JSON API with a GET getIamPolicy request:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/iam"

   Where:

   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the bucket whose Cloud IAM policy you want to view. For example, my-bucket.

3. Create a .json file that contains the policy you retrieved in the previous step.

4. Edit the .json file to remove the member from the policy.

5. Use cURL to call the JSON API with a PUT setIamPolicy request:

   curl -X PUT --data-binary @[JSON_FILE_NAME].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/iam"

   Where:

   • [JSON_FILE_NAME] is the name of the file you created in Step 3.
   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the bucket from which you want to remove member access. For example, my-bucket.

Important: It typically takes about a minute for revoking access to take effect. In some cases it may take longer. If you remove a user's access, this change is immediately reflected in the metadata; however, the user may still have access to the object for a short period of time.

Using Cloud IAM Conditions on buckets

Beta

This feature is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

The following sections show you how to add and remove Cloud IAM Conditions on your buckets. To view the Cloud IAM Conditions for your bucket, see Viewing the Cloud IAM policy for a bucket. For more information about using Cloud IAM Conditions with Cloud Storage, see Conditions.

You must enable uniform bucket-level access on the bucket before adding conditions.

Setting a new condition on a bucket

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. Click the Bucket overflow menu () on the far right of the row associated with the bucket.

3. Choose Edit bucket permissions.

4. Click Add members.

5. For New members, fill out the members to which you want to grant access to your bucket.

6. For each role to which you want to apply a condition:

   1. Select a Role to grant the members.

   2. Click Add condition to open the Edit condition form.

   3. Fill out the Title of the condition. The Description field is optional.

   4. Use the Condition Builder to build your condition visually, or use the Condition Editor tab to enter the CEL expression.

   5. Click Save to return to the Add members form. To add multiple roles, click Add another role.

7. Click Save.

gsutil

Note: gsutil must be at version 4.38 or higher to use conditions.

1. Use the gsutil iam command to save the bucket's Cloud IAM policy to a temporary JSON file.

   gsutil iam get gs://[BUCKET_NAME] > /tmp/policy.json

   Where [BUCKET_NAME] is the name of the bucket whose Cloud IAM policy you want to retrieve. For example, my-bucket.

2. Edit the /tmp/policy.json file in a text editor to add new conditions to the bindings in the Cloud IAM policy:

   {
     "version": [VERSION],
     "bindings": [
       {
         "role": "[IAM_ROLE]",
         "members": [
           "[MEMBER_NAME]"
         ],
         "condition": {
           "title": "[TITLE]",
           "description": "[DESCRIPTION]",
           "expression": "[EXPRESSION]"
         }
     ],
     "etag": "[ETAG]"
   }

   Where:

   • [VERSION] is the Cloud IAM policy version, which is required to be 3 for buckets with Cloud IAM Conditions.
   • [IAM ROLE] is the role to which the condition applies. For example, roles/storage.objectCreator.
   • [MEMBER_NAME] is the member to which the condition applies. For example, [e-mail].
   • [TITLE] is the title of the condition. For example, expires in 2019.
   • [DESCRIPTION] is an optional description of the condition. For example, Permission revoked on New Year's.
   • [EXPRESSION] is an attribute-based logic expression. For example, request.time < timestamp(\"2019-01-01T00:00:00Z\"). For more examples of expressions, see the Conditions attribute reference. Note that Cloud Storage only supports the date/time and resource name attributes.

   Do not modify [ETAG].

3. Use gsutil iam to set the modified Cloud IAM policy on the bucket.

   gsutil iam set /tmp/policy.json gs://[BUCKET_NAME]

Note: The gsutil iam ch command does not work with policies that contain conditions.

JSON

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use a GET getIamPolicy request to save the bucket's Cloud IAM policy to a temporary JSON file:

   curl \
   'https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/iam' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' > /tmp/policy.json

   Where:

   • [YOUR_ACCESS_TOKEN] is the access token you generated in Step 1.

3. Edit the /tmp/policy.json file in a text editor to add new conditions to the bindings in the Cloud IAM policy:

   {
         "version": [VERSION],
         "bindings": [
           {
             "role": "[IAM_ROLE]",
             "members": [
               "[MEMBER_NAME]"
             ],
             "condition": {
               "title": "[TITLE]",
               "description": "[DESCRIPTION]",
               "expression": "[EXPRESSION]"
             }
         ],
         "etag": "[ETAG]"
    }

   Where:

   • [VERSION] is the Cloud IAM policy version, which is required to be 3 for buckets with Cloud IAM Conditions.
   • [IAM_ROLE] is the role to which the condition applies. For example, roles/storage.objectCreator.
   • [MEMBER_NAME] is the member to which the condition applies. For example, [e-mail].
   • [TITLE] is the title of the condition. For example, expires in 2019.
   • [DESCRIPTION] is an optional description of the condition. For example, Permission revoked on New Year's.

   • [EXPRESSION] is an attribute-based logic expression. For example, request.time < timestamp(\"2019-01-01T00:00:00Z\"). For more examples of expressions, see the Conditions attribute reference. Note that Cloud Storage only supports the date/time and resource name attributes.

     Do not modify [ETAG].

4. Use a PUT setIamPolicy request to set the modified Cloud IAM policy on the bucket:

   curl -X PUT --data-binary @/tmp/policy.json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/iam"

   Where:

   • [YOUR_ACCESS_TOKEN] is the access token you generated in Step 1.

Removing a condition from a bucket

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. Click the Bucket overflow menu () on the far right of the row associated with the bucket.

3. Choose Edit bucket permissions.

4. Expand the role that contains the condition you are removing.

5. Click the Edit menu () for the member associated with the condition.

6. In the Edit permissions overlay that appears, click on the name of the condition you want to delete.

7. In the Edit condition overlay that appears, click Delete, then Confirm.

8. Click Save.

gsutil

Note: gsutil must be at version 4.38 or higher to use conditions.

1. Use the gsutil iam command to save the bucket's Cloud IAM policy to a temporary JSON file.

   gsutil iam get gs://[BUCKET_NAME] > /tmp/policy.json

2. Edit the /tmp/policy.json file in a text editor to remove conditions from the Cloud IAM policy.

3. Use gsutil iam to set the modified Cloud IAM policy on the bucket.

   gsutil iam set /tmp/policy.json gs://[BUCKET_NAME]

Note: The gsutil iam ch command does not work with policies that contain conditions.

JSON

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use a GET getIamPolicy request to save the bucket's Cloud IAM policy to a temporary JSON file:

   curl \
   'https://storage.googleapis.com/storage/v1/b/[BUCKET]/iam' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' > /tmp/policy.json

   Where:

   • [YOUR_ACCESS_TOKEN] is the access token you generated in Step 1.

3. Edit the /tmp/policy.json file in a text editor to remove conditions from the Cloud IAM policy.

4. Use a PUT setIamPolicy request to set the modified Cloud IAM policy on the bucket:

   curl -X PUT --data-binary @/tmp/policy.json \
     -H "Authorization: Bearer [YOUR_ACCESS_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/iam"

   Where:

   • [YOUR_ACCESS_TOKEN] is the access token you generated in Step 1.
   • [BUCKET_NAME] is the name of the bucket whose IAM policy you want to modify. For example, my-bucket.

Using Cloud IAM with projects

The following sections show how to complete basic Cloud IAM tasks on projects. Note that these tasks use a separate command line command, gcloud, and a separate endpoint, cloudresourcemanager.googleapis.com, compared to most Cloud Storage tasks.

To complete the following tasks, you must have the resourcemanager.projects.getIamPolicy and resourcemanager.projects.setIamPolicy Cloud IAM permissions.

Adding a member to a project-level policy

For a list of roles associated with Cloud Storage, see Cloud IAM Roles. For information on entities to which you grant Cloud IAM roles, see Member Types.

Console

1. Open the IAM & Admin browser in the Google Cloud Console.
   Open the IAM & Admin browser

2. In the project drop-down menu on the top bar, select the project to which you want to add a member.

3. Click Add. The Add members, roles to project dialog appears.

4. In the New members field, specify the name of the entity to which you are granting access.

5. In the Select a role drop down, grant the appropriate role to the member.

   Roles that affect Cloud Storage buckets and objects are found in the Project and Storage submenus.

6. Click Save.

gsutil

Project-level Cloud IAM policies are managed through the gcloud command, which is part of the Google Cloud SDK. To add a project-level policy, use gcloud beta projects add-iam-policy-binding.

JSON

Note: This task uses a separate endpoint compared to most Cloud Storage tasks.

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .json file that contains the following information:

   {
     "policy": {
       "version": "0",
       "bindings": {
         "role": "[IAM_ROLE]",
         "members": "[MEMBER_NAME]"
       },
     }
   }

   Where:

   • [IAM_ROLE] is the IAM role you are granting the member. For example, roles/storage.objectCreator.
   • [MEMBER_NAME] is the type and name of the member to which you are granting project access. For example, user:[e-mail].

3. Use cURL to call the Resource Manager API with a POST setIamPolicy request:

   curl -X POST --data-binary @[JSON_FILE_NAME].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://cloudresourcemanager.googleapis.com/v1/projects/[PROJECT_NAME]:setIamPolicy"

   Where:

   • [JSON_FILE_NAME] is the name of the file you created in Step 2.
   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [PROJECT_NAME] is the name of the project to which you are granting member access. For example, my-project.

Note: You should set the minimum permission possible that gives the member the required access. For example, if the team member only needs to read objects stored in a project, select the Storage Object Viewer permission. Similarly, if the team member needs full control of objects (but not buckets) in a project, select Storage Object Admin.

Viewing the Cloud IAM policy for a project

Console

1. Open the IAM & Admin browser in the Google Cloud Console.
   Open the IAM & Admin browser

2. In the project drop-down menu on the top bar, select the project whose policy you want to view.

3. There are two ways to view permissions for the project:

   • View by Members: View the Role column associated with individual members to see which roles each member has.
   • View by Roles: Use the drop-down associated with individual roles to see which members have the role.

gsutil

Project-level Cloud IAM policies are managed through the gcloud command, which is part of the Google Cloud SDK. To view the Cloud IAM policy of a project, use gcloud beta projects get-iam-policy command.

JSON

Note: This task uses a separate endpoint compared to most Cloud Storage tasks.

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the Resource Manager API with a POST getIamPolicy request:

   curl -X POST \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Length: 0" \
     "https://cloudresourcemanager.googleapis.com/v1/projects/[PROJECT_NAME]:getIamPolicy"

   Where:

   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [PROJECT_NAME] is the name of the project to which you are granting member access. For example, my-project.

Removing a member from a project-level policy

Console

1. Open the IAM & Admin browser in the Google Cloud Console.
   Open the IAM & Admin browser

2. In the project drop-down menu on the top bar, select the project from which you want to remove a member.

3. Make sure you are viewing permissions by Members, and select the members you want to remove.

4. Click Remove.

5. In the overlay window that appears, click Confirm.

gsutil

Project-level Cloud IAM policies are managed through the gcloud command, which is part of the Google Cloud SDK. To remove a project-level policy, use gcloud beta projects remove-iam-policy-binding.

JSON

Note: This task uses a separate endpoint compared to most Cloud Storage tasks.

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Get the existing policy applied to your project. To do so, use cURL to call the Resource Manager API with a POST getIamPolicy request:

   curl -X POST \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Length: 0" \
     "https://cloudresourcemanager.googleapis.com/v1/projects/[PROJECT_NAME]:getIamPolicy"

   Where:

   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [PROJECT_NAME] is the name of the project to which you want to add member access. For example, my-project.

3. Create a .json file that contains the policy you retrieved in the previous step.

4. Edit the .json file to remove the member from the policy.

5. Use cURL to call the Resource Manager API with a POST setIamPolicy request:

   curl -X POST --data-binary @[JSON_FILE_NAME].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://cloudresourcemanager.googleapis.com/v1/projects/[PROJECT_NAME]:setIamPolicy"

   Where:

   • [JSON_FILE_NAME] is the name of the file you created in Step 2.
   • [OAUTH2_TOKEN] is the access token you generated in Step 1.
   • [PROJECT_NAME] is the name of the project to which you want to grant member access. For example, my-project.

Important: It typically takes about a minute for revoking access to take effect. In some cases it may take longer. If you remove a user's access, this change is immediately reflected in the metadata; however, the user may still have access to the object for a short period of time.

What's next

• Learn how to publicly share your data.
• Learn more about Cloud IAM in Cloud Storage.
• See specific Sharing and collaboration examples.
• Learn about options to control access to your data.