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 using project convenience groups
(projectOwner, projectEditor, projectViewer) as the first segment of a binding
because these groups go against the principle of least privilege.
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 This flag can only be set if the policy exclusively uses
|
-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 member and a role that
is either granted or revoked.
You can use gsutil -m
to handle object-level operations in parallel.
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 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 member:
gsutil iam ch user:john.doe@example.com:objectCreator,objectViewer \
gs://ex-bucket
To specify a custom role for a particular member:
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 member. |
-R, -r | Performs This flag can only be set if the policy exclusively uses
|
-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. |