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

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 ...

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")

Description

The iam command has three sub-commands:

Get

The "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.

For example:

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.

Set

The "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 generated by "iam get".

The "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 "iam get". 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 Options

The "set" sub-command has the following options

-R, -r Performs "iam set" recursively to all objects under the specified bucket.
-a Performs "iam set" request 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.

Ch

The "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.

Ch Examples

Examples for the "ch" sub-command:

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

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

To make a bucket's objects publically 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 member:

gsutil iam ch user:john.doe@example.com:objectCreator,objectViewer \
              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

-R, -r Performs "iam ch" recursively 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.

Send feedback about...

Cloud Storage Documentation