iam - Get, set, or change bucket and/or object IAM permissions.

Synopsis

gsutil iam set [-afRr] [-e <etag>] file url ...
gsutil iam get url
gsutil iam ch [-fRr] binding ... url

where each binding is of the form:

    [-d] ("user"|"serviceAccount"|"domain"|"group"):id:role[,...]
    [-d] ("allUsers"|"allAuthenticatedUsers"):role[,...]
    -d ("user"|"serviceAccount"|"domain"|"group"):id
    -d ("allUsers"|"allAuthenticatedUsers")

NOTE: The "iam ch" command does not support changing Cloud IAM policies with
bindings that contain conditions. As such, "iam ch" cannot be used to add
conditions to a policy or to change the policy of a resource that already
contains conditions. See additional details below.

NOTE: The "gsutil iam" command does not allow you to add convenience values
(projectOwner, projectEditor, projectViewer), but you can remove existing
ones.

Description

Cloud Identity and Access Management (Cloud IAM) allows you to control who has access to the resources in your Google Cloud project. For more information, see Cloud Identity and Access Management.

The iam command has three sub-commands:

Get

The iam get command gets the Cloud IAM policy for a bucket or object, which you can save and edit for use with the iam set command.

The following examples save the bucket or object's Cloud IAM policy to a text file:

gsutil iam get gs://example > bucket_iam.txt
gsutil iam get gs://example/important.txt > object_iam.txt

The Cloud IAM policy returned by iam get includes an etag. The etag is used in the precondition check for iam set unless you override it using iam set -e.

Set

The iam set command sets a Cloud IAM policy on one or more buckets or objects, replacing the existing policy on those buckets or objects. For an example of the correct formatting for a Cloud IAM policy, see the output of the iam get command.

You can use the iam ch command to edit an existing policy, even in the presence of concurrent updates. You can also edit the policy concurrently using the -e flag to override the Cloud IAM policy's etag. Specifying -e with an empty string (i.e. gsutil iam set -e '' ...) instructs gsutil to skip the precondition check when setting the Cloud IAM policy.

When you set a Cloud IAM policy on a large number of objects, you should use the gsutil -m option for concurrent processing. The following command applies iam.txt to all objects in the dogs bucket:

gsutil -m iam set -r iam.txt gs://dogs

Note that only object-level operations are parallelized; setting a Cloud IAM policy on a large number of buckets with the -m flag does not improve performance.

Set Options

The set sub-command has the following options:

-R, -r

Performs iam set recursively on all objects under the specified bucket.

This flag can only be set if the policy exclusively uses roles/storage.legacyObjectReader or roles/storage.legacyObjectOwner. This flag cannot be used if the bucket is configured for uniform bucket-level access.

-a

Performs iam set on all object versions.

-e <etag>

Performs the precondition check on each object with the specified etag before setting the policy. You can retrieve the policy's etag using iam get.

-f

The default gsutil error-handling mode is fail-fast. This flag changes the request to fail-silent mode. This option is implicitly set when you use the gsutil -m option.

Ch

The iam ch command incrementally updates Cloud IAM policies. You can specify multiple access grants or removals in a single command. The access changes are applied as a batch to each url in the order in which they appear in the command line arguments. Each access change specifies a principal and a role that is either granted or revoked.

You can use gsutil -m to handle object-level operations in parallel.

Note: The iam ch command cannot be used to change the Cloud IAM policy of a resource that contains conditions in its policy bindings. Attempts to do so result in an error. To change the Cloud IAM policy of such a resource, you can perform a read-modify-write operation by saving the policy to a file using iam get, editing the file, and setting the updated policy using iam set.

Ch Examples

Examples for the ch sub-command:

To grant a single role to a single principal for some targets:

gsutil iam ch user:john.doe@example.com:objectCreator gs://ex-bucket

To make a bucket's objects publicly readable:

gsutil iam ch allUsers:objectViewer gs://ex-bucket

To grant multiple bindings to a bucket:

gsutil iam ch user:john.doe@example.com:objectCreator \
              domain:www.my-domain.org:objectViewer gs://ex-bucket

To specify more than one role for a particular principal:

gsutil iam ch user:john.doe@example.com:objectCreator,objectViewer \
              gs://ex-bucket

To specify a custom role for a particular principal:

gsutil iam ch user:john.doe@example.com:roles/customRoleName gs://ex-bucket

To apply a grant and simultaneously remove a binding to a bucket:

gsutil iam ch -d group:readers@example.com:legacyBucketReader \
              group:viewers@example.com:objectViewer gs://ex-bucket

To remove a user from all roles on a bucket:

gsutil iam ch -d user:john.doe@example.com gs://ex-bucket

Ch Options

The ch sub-command has the following options:

-d

Removes roles granted to the specified principal.

-R, -r

Performs iam ch recursively to all objects under the specified bucket.

-f

The default gsutil error-handling mode is fail-fast. This flag changes the request to fail-silent mode. This is implicitly set when you invoke the gsutil -m option.