Set and manage IAM policies on buckets (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources

• Cross-product tools

• Console

• Discover

• Product overview

• Storage Intelligence overview

• Get started

• Terraform support for Cloud Storage

• Configure and manage Storage Intelligence

• Create buckets

• Create a bucket

• Domain-named bucket verification

• Access and manage buckets

• List buckets

• Change the default storage class of a bucket

• Move and rename buckets

• Delete buckets

• Upload and download objects

• About objects

• Overview of uploads and downloads

• Access and manage objects

• List objects

• Copy, rename, and move objects

• Change an object's storage class

• Tools to access and manage objects using a directory structure

• Object transcoding

• Delete objects

• Get insights on your stored data

• Analyze stored data with Gemini Cloud Assist

• Cache objects

• About caching

• Control data lifecycles

• Options for controlling data lifecycles

• Make requests

• Consistency in Cloud Storage operations

• Batched requests

• Use long-running operations

• Paginate results

• URI wildcards

• Secure data

• Access control

  • Overview
  • Bucket IP filtering
    * Overview
    * Create a bucket with IP filtering rules
    * Create or update IP filtering rules on an existing bucket
    * Get IP bucket filtering rules
    * List bucket IP filtering rules
    * Delete bucket IP filtering rules
    * Disable bucket IP filtering
    * Bypass bucket IP filtering rules
  • Sharing and collaboration scenarios
  • Access control best practices

• Monitor data and usage

• Use Cloud Audit Logs with Cloud Storage

• Usage logs and storage logs

• Use Cloud Audit Logs with storage batch operations

• Use Cloud Logs with storage batch operations

• Use Cloud Audit Logs with Storage Insights

• Use gRPC client-side metrics

• Use client-side traces

• Protection, backup, and recovery

• Overview

• Soft delete

  • Overview
  • Set and manage soft delete policies
  • Use soft-deleted objects
  • Use soft-deleted buckets
  • Set a default soft delete retention duration
  • Use soft delete recommendations
  • Disable soft delete

• Mount buckets with Cloud Storage FUSE

• Overview

• Quickstart

• Install Cloud Storage FUSE

• Mount buckets

• Performance

  • Performance tuning best practices
  • Profile-based configurations for AI/ML workloads
  • Automated configuration values for high-performance machine types
  • Use pre-configured GKE YAML files to optimize Cloud Storage FUSE performance

• Work across products, Clouds, and platforms

• Best practices for media workloads

• Interoperability

• Use Cloud Storage with Big Data

• Integration with Google Cloud Platform services and tools

• Troubleshoot

• Troubleshooting common issues

• Troubleshooting Storage Insights issues

• Troubleshooting Cloud Storage FUSE issues

Set and manage IAM policies on buckets

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:

• To learn about how to get finer-grained control over groups of objects, seeSet and manage IAM policies on managed folders.
• For an alternative way to control access to individual objects in your buckets, see Access Control Lists.
• For more information about controlling access to Cloud Storage resources, read Overview of Access Control.

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:

• storage.buckets.get
• storage.buckets.getIamPolicy
• storage.buckets.setIamPolicy
• storage.buckets.update
• storage.buckets.list
  • This permission is only required if you plan on using the Google Cloud console to perform the tasks on this page.

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, seeIAM Roles. For information on entities to which you grant IAM roles, see Principal identifiers.

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket for which you want to grant a principal a role.
3. Select the Permissions tab near the top of the page.
4. Click the Grant access button.
   The Add principals dialog appears.
5. In the New principals field, enter one or more identities that need access to your bucket.
6. 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.
7. Click Save.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

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 roleyou are granting to the principal. For example, roles/storage.objectViewer.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Create a JSON file that contains the following information:
   {
   "bindings":[
   {
   "role": "IAM_ROLE",
   "members":[
   "PRINCIPAL_IDENTIFIER"
   ]
   }
   ]
   }
   Where:
   • IAM_ROLE is the IAM roleyou 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.
3. Use cURL to call the JSON API with aPUT 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

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket whose policy you want to view.
3. In the Bucket details page, click the Permissions tab.
   The IAM policy that applies to the bucket appears in the Permissions section.
4. 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.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with aGET 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.

Remove a principal from a bucket-level policy

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket from which you want to remove a principal's role.
3. In the Bucket details page, click the Permissions tab.
   The IAM policy that applies to the bucket appears in the Permissions section.
4. In the View by principals tab, select the checkbox for the principal you're removing.
5. Click the - Remove access button.
6. 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, seeTroubleshooting.

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 roleyou are revoking. For example, roles/storage.objectViewer.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Get the existing policy applied to your bucket. To do so, usecURL to call the JSON API with aGET 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.
3. Create a JSON file that contains the policy you retrieved in the previous step.
4. Edit the JSON file to remove the principal from the policy.
5. Use cURL to call the JSON API with aPUT 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.

Use IAM Conditions on buckets

The following sections show you how to add and removeIAM Conditions on your buckets. To view the IAM Conditions for your bucket, seeViewing the IAM policy for a bucket. For more information about using IAM Conditions with Cloud Storage, seeConditions.

You must enable uniform bucket-level access on the bucket before adding conditions.

Set a new condition on a bucket

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket that you want to add a new condition for.
3. In the Bucket details page, click the Permissions tab.
   The IAM policy that applies to the bucket appears in the Permissions section.
4. Click + Grant access.
5. For New principals, fill out the principals to which you want to grant access to your bucket.
6. For each role to which you want to apply a condition:
   1. Select a Role to grant the principals.
   2. Click Add condition to open the Edit condition form.
   3. Fill out the Title of the condition. The Description field is optional.
   4. Use the Condition builder to build your condition visually, or use theCondition editor tab to enter the CEL expression.
   5. Click Save to return to the Add principal form. To add multiple roles, click Add another role.
7. Click Save.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

1. Create a JSON or YAML file that defines the condition, including thetitle of the condition, the attribute-based logicexpression 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 theexpression.
2. 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 roleyou 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.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. 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.
3. 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 theIAM 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, seePrincipal 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-basedlogic 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.
4. 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

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket that you want to remove a condition from.
3. In the Bucket details page, click the Permissions tab.
   The IAM policy that applies to the bucket appears in the Permissions section.
4. Click the Edit icon for the principal associated with the condition.
5. In the Edit access overlay that appears, click the name of the condition you want to delete.
6. In the Edit condition overlay that appears, click Delete, thenConfirm.
7. Click Save.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

1. 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
2. Edit the tmp-policy.json file in a text editor to remove conditions from the IAM policy.
3. 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

Code samples

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. 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.
3. Edit the tmp-policy.json file in a text editor to remove conditions from the IAM policy.
4. 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

• Learn how to publicly share your data.
• See specific Sharing and collaboration examples.
• Learn about best practices when using IAM.
• Learn how to use role recommendations for buckets.
• To troubleshoot failed operations related to IAM roles and permissions, see Troubleshooting.

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 2025-12-09 UTC.