Skip to main content
Send feedback
Set and manage IAM policies on buckets Stay organized with collections
Save and categorize content based on your preferences.
Overview
This page describes how to set Identity and Access Management (IAM) policies
on
buckets, so you can control access to objects and managed folders within those
buckets.
If you're looking for other methods of access control, see the following
resources:
Note: IAM policies cannot be managed using the XML API.
Required roles
To get the permissions that you need to set and manage IAM
policies for a bucket, ask your administrator to grant you the Storage Admin
( roles/storage.admin
) IAM role for the bucket.
This role contains the following permissions, which are required to set
and manage IAM policies for buckets:
You can also get these permissions with custom roles
.
Add a principal to a bucket-level policy
For a list of roles associated with Cloud Storage, see IAM Roles
. For information on entities to which you grant
IAM roles, see Principal identifiers
.
Console
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
In the list of buckets, click the name of the bucket for which you want
to grant a principal a role.
Select the Permissions tab near the top of the page.
Click the add_box
Grant access button.
The Add principals
dialog appears.
In the New principals field, enter one or more identities
that need access to your bucket.
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.
Click Save .
To learn how to get detailed error information about failed Cloud Storage
operations in the Google Cloud console, see Troubleshooting
.
Command line
Use the buckets add-iam-policy-binding
command
:
gcloud storage buckets add-iam-policy-binding gs:// BUCKET_NAME
--member= PRINCIPAL_IDENTIFIER
--role= IAM_ROLE
Where:
BUCKET_NAME
is the name of the bucket you are
granting the principal access to. For example, my-bucket
.
PRINCIPAL_IDENTIFIER
identifies who you are
granting bucket access to. For example, user:jeffersonloveshiking@gmail.com
. For
a list of principal identifier formats, see Principal identifiers
.
IAM_ROLE
is the IAM role
you are granting to the principal. For example, roles/storage.objectViewer
.
REST APIs
JSON
Have gcloud CLI installed and initialized
, which lets
you generate an access token for the Authorization
header.
Create a JSON file that contains the following information:
{
"bindings"
:[
{
"role"
:
" IAM_ROLE
" ,
"members"
:[
" PRINCIPAL_IDENTIFIER
" ]
}
]
}
Where:
IAM_ROLE
is the IAM role
you are granting. For example, roles/storage.objectViewer
.
PRINCIPAL_IDENTIFIER
identifies who you are
granting bucket access to. For example, user:jeffersonloveshiking@gmail.com
. For a
list of principal identifier formats, see Principal identifiers
.
Use cURL
to call the JSON API
with a PUT setIamPolicy
request:
curl -X PUT --data-binary @ JSON_FILE_NAME
\
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME
/iam"
Where:
JSON_FILE_NAME
is the path for the file
that you created in Step 2.
BUCKET_NAME
is the name of the bucket to
which you want to give the principal access. For example, my-bucket
.
View the IAM policy for a bucket
Console
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
In the list of buckets, click the name of the bucket whose policy you
want to view.
In the Bucket details page, click the Permissions tab.
The IAM policy that applies to the bucket appears in
the Permissions section.
Optional: Use the Filter bar to filter your results.
If you search by principal, your results display each role that the
principal is granted.
Command line
Use the buckets get-iam-policy
command
:
gcloud storage buckets get-iam-policy gs:// BUCKET_NAME
Where BUCKET_NAME
is the name of the bucket
whose IAM policy you want to view. For example, my-bucket
.
Note: Some roles may not appear in the bucket permissions window. If you
grant roles at the project level, they don't 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
.
Remove a principal from a bucket-level policy
Console
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
In the list of buckets, click the name of the bucket from which you want
to remove a principal's role.
In the Bucket details page, click the Permissions tab.
The IAM policy that applies to the bucket appears in
the Permissions section.
In the View by principals tab, select the checkbox for the
principal you're removing.
Click the - Remove access button.
In the overlay window that appears, click Confirm .
To learn how to get detailed error information about failed Cloud Storage
operations in the Google Cloud console, see Troubleshooting
.
Command line
Use the buckets remove-iam-policy-binding
command
:
gcloud storage buckets remove-iam-policy-binding gs:// BUCKET_NAME
--member= PRINCIPAL_IDENTIFIER
--role= IAM_ROLE
Where:
BUCKET_NAME
is the name of the bucket you are
revoking access to. For example, my-bucket
.
PRINCIPAL_IDENTIFIER
identifies who you are
revoking access from. For example, user:jeffersonloveshiking@gmail.com
. For a
list of principal identifier formats, see Principal identifiers
.
IAM_ROLE
is the IAM role
you are revoking. For example, roles/storage.objectViewer
.
REST APIs
JSON
Have gcloud CLI installed and initialized
, which lets
you generate an access token for the Authorization
header.
Get the existing policy applied to your bucket. To do so, use cURL
to call the JSON API
with a GET getIamPolicy
request:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME
/iam"
Where BUCKET_NAME
is the name of the bucket
whose IAM policy you want to view. For example, my-bucket
.
Create a JSON file that contains the policy you retrieved in the
previous step.
Edit the JSON file to remove the principal from the policy.
Use cURL
to call the JSON API
with a PUT setIamPolicy
request:
curl -X PUT --data-binary @ JSON_FILE_NAME
\
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME
/iam"
Where:
JSON_FILE_NAME
is the path for the file
that you created in Step 3.
BUCKET_NAME
is the name of the bucket from
which you want to remove 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.
Use IAM Conditions on buckets
The following sections show you how to add and remove IAM Conditions
on your buckets. To view the
IAM Conditions for your bucket, see Viewing the IAM policy for a bucket
. For more information
about using IAM Conditions with Cloud Storage, see Conditions
.
You must enable uniform bucket-level access
on the bucket before adding conditions.
Set a new condition on a bucket
Console
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
In the list of buckets, click the name of the bucket that you want to add
a new condition for.
In the Bucket details page, click the Permissions tab.
The IAM policy that applies to the bucket appears in
the Permissions section.
Click + Grant access .
For New principals , fill out the principals to which you want to grant
access to your bucket.
For each role to which you want to apply a condition:
Select a Role to grant the principals.
Click Add condition to open the Edit condition form.
Fill out the Title of the condition. The Description field is
optional.
Use the Condition builder to build your condition visually, or use the Condition editor tab to enter the CEL expression
.
Click Save to return to the Add principal form. To add
multiple roles, click Add another role .
Click Save .
To learn how to get detailed error information about failed Cloud Storage
operations in the Google Cloud console, see Troubleshooting
.
Command line
Create a JSON or YAML file that defines the condition, including the title
of the condition, the attribute-based
logic expression
for the condition, and, optionally, a description
for
the condition.
Note that Cloud Storage only supports the date/time
, resource type
, and resource name
attributes in the expression
.
Use the buckets add-iam-policy-binding
command
with the --condition-from-file
flag:
gcloud storage buckets add-iam-policy-binding gs:// BUCKET_NAME
--member= PRINCIPAL_IDENTIFIER
--role= IAM_ROLE
--condition-from-file= CONDITION_FILE
Where:
BUCKET_NAME
is the name of the bucket you are
granting the principal access to. For example, my-bucket
.
PRINCIPAL_IDENTIFIER
identifies who the
condition applies to. For example, user:jeffersonloveshiking@gmail.com
. For a
list of principal identifier formats, see Principal identifiers
.
IAM_ROLE
is the IAM role
you are granting to the principal. For example, roles/storage.objectViewer
.
CONDITION_FILE
is the file you created in the
previous step.
Alternatively, you can include the condition directly in the command
with the --condition
flag instead of the --condition-from-file
flag.
REST APIs
JSON
Have gcloud CLI installed and initialized
, which lets
you generate an access token for the Authorization
header.
Use a GET getIamPolicy
request to save the bucket's
IAM policy to a temporary JSON file:
curl \
'https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME
/iam' \
--header 'Authorization: Bearer $(gcloud auth print-access-token)' > tmp-policy.json
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
Edit the tmp-policy.json
file in a text editor to add new conditions
to the bindings in the IAM policy:
{
"version": VERSION
,
"bindings": [
{
"role": " IAM_ROLE
",
"members": [
" PRINCIPAL_IDENTIFIER
"
],
"condition": {
"title": " TITLE
",
"description": " DESCRIPTION
",
"expression": " EXPRESSION
"
}
}
],
"etag": " ETAG
"
}
Where:
VERSION
is the IAM policy version
, which is required to be 3
for buckets with IAM Conditions.
IAM_ROLE
is the role to which the condition
applies. For example, roles/storage.objectViewer
.
PRINCIPAL_IDENTIFIER
identifies who the
condition applies to. For example, user:jeffersonloveshiking@gmail.com
.
For a list of principal identifier formats, see Principal identifiers
.
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
, resource type
, and resource name
attributes.
Don't modify ETAG
.
Use a PUT setIamPolicy
request to set the modified
IAM policy on the bucket:
curl -X PUT --data-binary @tmp-policy.json \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME
/iam"
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
Remove a condition from a bucket
Console
In the Google Cloud console, go to the Cloud Storage Buckets
page. Go to Buckets
In the list of buckets, click the name of the bucket that you want to
remove a condition from.
In the Bucket details page, click the Permissions tab.
The IAM policy that applies to the bucket appears in
the Permissions section.
Click the Edit icon edit
for the principal
associated with the condition.
In the Edit access overlay that appears, click the name of the
condition you want to delete.
In the Edit condition overlay that appears, click Delete , then Confirm .
Click Save .
To learn how to get detailed error information about failed Cloud Storage
operations in the Google Cloud console, see Troubleshooting
.
Command line
Use the buckets get-iam-policy
command
to save the bucket's
IAM policy to a temporary JSON file.
gcloud storage buckets get-iam-policy gs:// BUCKET_NAME
> tmp-policy.json
Edit the tmp-policy.json
file in a text editor to remove
conditions from the IAM policy.
Use buckets set-iam-policy
to set the modified
IAM policy on the bucket.
gcloud storage buckets set-iam-policy gs:// BUCKET_NAME
tmp-policy.json
REST APIs
JSON
Have gcloud CLI installed and initialized
, which lets
you generate an access token for the Authorization
header.
Use a GET getIamPolicy
request to save the bucket's
IAM policy to a temporary JSON file:
curl \
'https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME
/iam' \
--header 'Authorization: Bearer $(gcloud auth print-access-token)' > tmp-policy.json
Where BUCKET_NAME
is the name of the bucket
you are granting access to. For example, my-bucket
.
Edit the tmp-policy.json
file in a text editor to remove conditions
from the IAM policy.
Use a PUT setIamPolicy
request to set the modified
IAM policy on the bucket:
curl -X PUT --data-binary @tmp-policy.json \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME
/iam"
Where BUCKET_NAME
is the name of the bucket
whose IAM policy you want to modify. For example, my-bucket
.
Best practices
You should set the minimum role needed to give the principal
the required access. For example, if a team member only needs to read
objects stored in a bucket, grant them the Storage Object Viewer
( roles/storage.objectViewer
) role instead of the Storage Object Admin
( roles/storage.objectAdmin
) role. Similarly, if the team member needs full
control of objects in the bucket but not the bucket itself, grant them the
Storage Object Admin ( roles/storage.objectAdmin
) role instead of the
Storage Admin ( roles/storage.admin
) role.
What's next
Send feedback
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-05-29 UTC.
Need to tell us more?
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-05-29 UTC."],[],[]]
