iam - Get, set, or change bucket and/or object IAM permissions.
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 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 disallows using project convenience groups (projectOwner, projectEditor, projectViewer) as the first segment of a binding because these groups go against the principle of least privilege.
The iam command has three sub-commands:
iam get command gets the IAM policy for a bucket or object, which you
can save and edit for use with the
iam set command.
gsutil iam get gs://example > bucket_iam.txt gsutil iam get gs://example/important.txt > object_iam.txt
The IAM policy returned by
iam get includes the etag of the IAM policy and
will be used in the precondition check for
iam set, unless the etag is
overridden by setting the
iam set -e option.
iam set command sets the IAM policy for one or more buckets and / or
objects. It overwrites the current IAM policy that exists on a bucket (or
object) with the policy specified in the input file. The
iam set command
takes as input a file with an IAM policy in the format of the output
iam ch command can be used to edit an existing policy. It works
correctly in the presence of concurrent updates. You may also do this
manually by using the -e flag and overriding the etag returned in
Specifying -e with an empty string (i.e.
gsutil iam set -e '' ...) will
instruct gsutil to skip the precondition check when setting the IAM policy.
If you wish to set an IAM policy on a large number of objects, you may want to use the gsutil -m option for concurrent processing. The following command will apply iam.txt to all objects in the "cats" bucket.
gsutil -m iam set -r iam.txt gs://cats
Note that only object-level IAM applications are parallelized; you do not gain any additional performance when applying an IAM policy to a large number of buckets with the -m flag.
set sub-command has the following options
-R, -r Performs
iam setrecursively to all objects under the specified bucket.
iam setrequest on all object versions.
-e <etag> Performs the precondition check on each object with the specified etag before setting the policy. -f Default gsutil error handling is fail-fast. This flag changes the request to fail-silent mode. This is implicitly set when invoking the gsutil -m option.
iam ch command incrementally updates IAM policies. You may specify
multiple access grants and removals in a single command invocation, which
will be batched and applied as a whole to each url via an IAM patch.
The patch will be constructed by applying each access grant or removal in the
order in which they appear in the command line arguments. Each access change
specifies a member and the role that will be either granted or revoked.
The gsutil -m option may be set to handle object-level operations more efficiently.
iam ch command may NOT be used to change the IAM policy of a
resource that contains conditions in its policy bindings. Attempts to do so
will result in an error. To change the IAM policy of such a resource, you can
perform a read-modify-write operation by using
gsutil iam get to save the
policy to a file, editing the file, and using
gsutil iam set to set the
Examples for the
To grant a single role to a single member for some targets:
gsutil iam ch user:firstname.lastname@example.org: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:email@example.com:objectCreator \ domain:www.my-domain.org:objectViewer gs://ex-bucket
To specify more than one role for a particular member:
gsutil iam ch user:firstname.lastname@example.org:objectCreator,objectViewer \ gs://ex-bucket
To specify a custom role for a particular member:
gsutil iam ch user:email@example.com:roles/customRoleName gs://ex-bucket
To apply a grant and simultaneously remove a binding to a bucket:
gsutil iam ch -d group:firstname.lastname@example.org:legacyBucketReader \ group:email@example.com:objectViewer gs://ex-bucket
To remove a user from all roles on a bucket:
gsutil iam ch -d user:firstname.lastname@example.org gs://ex-bucket
ch sub-command has the following options
-R, -r Performs
iam chrecursively to all objects under the specified bucket.
-f Default gsutil error handling is fail-fast. This flag changes the request to fail-silent mode. This is implicitly set when invoking the gsutil -m option.