This page describes how to control access to buckets and objects using Identity and Access Management (IAM) permissions. IAM allows you to control who has access to your buckets and objects.
To learn about other ways to control access to buckets and objects, read Overview of Access Control. To learn about controlling access to individual objects in your buckets, see Access Control Lists.
Use IAM with buckets
The following sections show how to complete basic IAM tasks on buckets.
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 Types.
Console
- In the Google Cloud console, go to the Cloud Storage Browser page.
Click the Bucket overflow menu (
) associated with the bucket to which you want to grant a principal a role.
Choose Edit access.
Click the + Add principal button.
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 operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the gsutil iam ch
command:
gsutil iam ch PRINCIPAL_TYPE:PRINCIPAL_NAME:IAM_ROLE gs://BUCKET_NAME
Where:
PRINCIPAL_TYPE
is the type of principal to which you are granting bucket access. For example,user
.PRINCIPAL_NAME
is the name of the principal to which you are granting bucket access. For example,jane@gmail.com
.IAM_ROLE
is the IAM role you are granting to the principal. For example,objectViewer
.BUCKET_NAME
is the name of the bucket you are granting the principal access to. For example,my-bucket
.
For more examples of how to format
PRINCIPAL_TYPE:PRINCIPAL_NAME:IAM_ROLE
,
see the gsutil iam ch
reference page.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Create a JSON file that contains the following information:
{ "bindings":[ { "role": "IAM_ROLE", "members":[ "PRINCIPAL_NAME" ] } ] }
Where:
Use
cURL
to call the JSON API with aPUT setIamPolicy
request:curl -X PUT --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer OAUTH2_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.OAUTH2_TOKEN
is the access token you generated in Step 1.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 Browser page.
Click the Bucket overflow menu (
) associated with the bucket whose policy you want to view.
Choose Edit access.
Expand the desired role to view the principals who have that role.
(Optional) Use the search bar to filter your results by role or principal.
If you search by principal, your results display each role that the principal is granted.
gsutil
Use the gsutil iam get
command:
gsutil iam get gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the bucket whose
IAM policy you want to view. For example, my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the JSON API with aGET getIamPolicy
request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/iam"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.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
- In the Google Cloud console, go to the Cloud Storage Browser page.
Click the Bucket overflow menu (
) associated with the bucket from which you want to remove a principal's role.
Choose Edit access.
Expand the role that contains the principal you are removing.
Click on the trash icon.
In the overlay window that appears, click Remove.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the gsutil iam ch
command with a -d
flag:
gsutil iam ch -d PRINCIPAL_TYPE:PRINCIPAL_NAME gs://BUCKET_NAME
Where:
PRINCIPAL_TYPE
is the type of the principal you are removing from the policy. For example,user
.PRINCIPAL_NAME
is the name of the principal you are removing from the policy. For example,jane@gmail.com
.BUCKET_NAME
is the name of the bucket from which you are removing access. For example,my-bucket
.
For more examples of how to format
PRINCIPAL_TYPE:PRINCIPAL_NAME
, see the
gsutil iam ch
reference page.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Get the existing policy applied to your project. To do so, use
cURL
to call the JSON API with aGET getIamPolicy
request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/iam"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.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 aPUT setIamPolicy
request:curl -X PUT --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer OAUTH2_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.OAUTH2_TOKEN
is the access token you generated in Step 1.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 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 Browser page.
Click the Bucket overflow menu (
) on the far right of the row associated with the bucket.
Choose Edit access.
Click Add principal.
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 operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the
gsutil iam
command to save the bucket's IAM policy to a temporary JSON file.gsutil iam get gs://BUCKET_NAME > /tmp/policy.json
Where
BUCKET_NAME
is the name of the bucket whose IAM policy you want to retrieve. 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_NAME" ], "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_NAME
is the principal to which the condition applies. For example,jane@gmail.com
.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.
Do not modify
ETAG
.Use
gsutil iam
to set the modified IAM policy on the bucket.gsutil iam set /tmp/policy.json gs://BUCKET_NAME
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
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 OAUTH2_TOKEN' > /tmp/policy.json
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.
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_NAME" ], "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_NAME
is the principal to which the condition applies. For example,user:jane@gmail.com
.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.Do not 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 OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/iam"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.
Remove a condition from a bucket
Console
- In the Google Cloud console, go to the Cloud Storage Browser page.
Click the Bucket overflow menu (
) on the far right of the row associated with the bucket.
Choose Edit access.
Expand the role that contains the condition you are removing.
Click the Edit menu (
) for the principal associated with the condition.
In the Edit access overlay that appears, click on 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 operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the
gsutil iam
command to save the bucket's IAM policy to a temporary JSON file.gsutil iam get gs://BUCKET_NAME > /tmp/policy.json
Edit the
/tmp/policy.json
file in a text editor to remove conditions from the IAM policy.Use
gsutil iam
to set the modified IAM policy on the bucket.gsutil iam set /tmp/policy.json gs://BUCKET_NAME
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
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 OAUTH2_TOKEN' > /tmp/policy.json
Where:
BUCKET_NAME
is the name of the bucket you are granting access to. For example,my-bucket
.OAUTH2_TOKEN
is the access token you generated in Step 1.
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 OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/iam"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket whose IAM policy you want to modify. For example,my-bucket
.
Use IAM with projects
The following sections show how to complete basic IAM tasks on
projects. Note that these tasks use a separate command line command, gcloud
,
and a separate endpoint, cloudresourcemanager.googleapis.com
, compared to most
Cloud Storage tasks.
To complete the following tasks, you must have the
resourcemanager.projects.getIamPolicy
and
resourcemanager.projects.setIamPolicy
IAM permissions.
Add a principal to a project-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 Types.
Console
- Open the IAM & Admin browser in the Google Cloud console.
Open the IAM & Admin browser In the project drop-down menu on the top bar, select the project to which you want to add a principal.
Click Add. The Add principals, roles to project dialog appears.
In the New principals field, specify the name of the entity to which you are granting access.
In the Select a role drop down, grant the appropriate role to the principal.
Roles that affect Cloud Storage buckets and objects are found in the Project and Storage submenus.
Click Save.
gsutil
Project-level IAM policies are managed through the gcloud
command. To add a project-level policy, use
gcloud beta projects add-iam-policy-binding
.
JSON
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Create a JSON file that contains the following information:
{ "policy": { "version": "0", "bindings": { "role": "IAM_ROLE", "members": "PRINCIPAL_NAME" }, } }
Where:
IAM_ROLE
is the IAM role you are granting. For example,roles/storage.objectViewer
.PRINCIPAL_NAME
is the type and name of the principal to which you are granting project access. For example,user:jane@gmail.com
.
Use
cURL
to call the Resource Manager API with aPOST setIamPolicy
request:curl -X POST --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:setIamPolicy"
Where:
JSON_FILE_NAME
is the path for the file that you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID of the project to which you are granting access. For example,my-project
.
View the IAM policy for a project
Console
- Open the IAM & Admin browser in the Google Cloud console.
Open the IAM & Admin browser In the project drop-down menu on the top bar, select the project whose policy you want to view.
There are two ways to view permissions for the project:
- View by Principals: View the Role column associated with individual principals to see which roles each principal has.
- View by Roles: Use the drop-down associated with individual roles to see which principals have the role.
gsutil
Project-level IAM policies are managed through the gcloud
command. To view the IAM policy of a project, use
gcloud beta projects get-iam-policy
command.
JSON
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the Resource Manager API with aPOST getIamPolicy
request:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Length: 0" \ "https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:getIamPolicy"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID of the project to which you are granting access. For example,my-project
.
Remove a principal from a project-level policy
Console
- Open the IAM & Admin browser in the Google Cloud console.
Open the IAM & Admin browser In the project drop-down menu on the top bar, select the project from which you want to remove a principal.
Make sure you are viewing permissions by Principals, and select the principals you want to remove.
Click Remove.
In the overlay window that appears, click Confirm.
gsutil
Project-level IAM policies are managed through the gcloud
command. To remove a project-level policy, use
gcloud beta projects remove-iam-policy-binding
.
JSON
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Get the existing policy applied to your project. To do so, use
cURL
to call the Resource Manager API with aPOST getIamPolicy
request:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Length: 0" \ "https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:getIamPolicy"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID of the project from which you want to remove access. For example,my-project
.
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 Resource Manager API with aPOST setIamPolicy
request:curl -X POST --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:setIamPolicy"
Where:
JSON_FILE_NAME
is the path for the file that you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID of the project from which which you want to remove access. For example,my-project
.
What's next
- Learn how to publicly share your data.
- Learn more about IAM in Cloud Storage.
- See specific Sharing and collaboration examples.
- Learn about options to control access to your data.
- Learn about best practices when using IAM.