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.
Using IAM with buckets
The following sections show how to complete basic IAM tasks on buckets.
Adding a member 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 Member Types.
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click the Bucket overflow menu (
) associated with the bucket to which you want to grant a member a role.
Choose Edit bucket permissions.
Click the + Add members button.
In the New members 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.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil iam ch
command:
gsutil iam ch MEMBER_TYPE:MEMBER_NAME:IAM_ROLE gs://BUCKET_NAME
Where:
MEMBER_TYPE
is the type of member to which you are granting bucket access. For example,user
.MEMBER_NAME
is the name of the member to which you are granting bucket access. For example,jane@gmail.com
.IAM_ROLE
is the IAM role you are granting to the member. For example,roles/storage.objectViewer
.BUCKET_NAME
is the name of the bucket you are granting the member access to. For example,my-bucket
.
For more examples of how to format
MEMBER_TYPE:MEMBER_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.
Create a .json file that contains the following information:
{ "bindings":[ { "role": "IAM_ROLE", "members":[ "MEMBER_NAME" ] } ] }
Where:
Use
cURL
to call the JSON API with aPUT setIamPolicy
request:curl -X PUT --data-binary @JSON_FILE_NAME.json \ -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 name of the file 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 member access. For example,my-bucket
.
Viewing the IAM policy for a bucket
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click the Bucket overflow menu (
) associated with the bucket to which you want to view role members.
Choose Edit bucket permissions.
Expand the desired role to view the members who have been assigned to it.
(Optional) Use the search bar to filter your results by role or member.
If you search by member, your results display each role that the member is assigned to.
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.
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
.
Removing a member from a bucket-level policy
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click the Bucket overflow menu (
) associated with the bucket from which you want to remove a member's role.
Choose Edit bucket permissions.
Expand the role that contains the member you are removing.
Click on the trash icon.
In the overlay window that appears, click Remove.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil iam ch
command with a -d
flag:
gsutil iam ch -d MEMBER_TYPE:MEMBER_NAME gs://BUCKET_NAME
Where:
MEMBER_TYPE
is the type of the member you are removing from the policy. For example,user
.MEMBER_NAME
is the name of the member you are removing from the policy. For example,jane@gmail.com
.BUCKET_NAME
is the name of the bucket from which you are removing member access. For example,my-bucket
.
For more examples of how to format
MEMBER_TYPE:MEMBER_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.
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 member from the policy.
Use
cURL
to call the JSON API with aPUT setIamPolicy
request:curl -X PUT --data-binary @JSON_FILE_NAME.json \ -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 name of the file 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 member access. For example,my-bucket
.
Using 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.
Setting a new condition on a bucket
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click the Bucket overflow menu (
) on the far right of the row associated with the bucket.
Choose Edit bucket permissions.
Click Add members.
For New members, fill out the members 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 members.
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 members form. To add multiple roles, click Add another role.
Click Save.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
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": [ "MEMBER_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
.MEMBER_NAME
is the member 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.
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": [ "MEMBER_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
.MEMBER_NAME
is the member 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 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.
Removing a condition from a bucket
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click the Bucket overflow menu (
) on the far right of the row associated with the bucket.
Choose Edit bucket permissions.
Expand the role that contains the condition you are removing.
Click the Edit menu (
) for the member associated with the condition.
In the Edit permissions 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.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
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.
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 the member 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
.
Using 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.
Adding a member 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 Member 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 member.
Click Add. The Add members, roles to project dialog appears.
In the New members 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 member.
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, which is part of the Google Cloud SDK. 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.
Create a .json file that contains the following information:
{ "policy": { "version": "0", "bindings": { "role": "IAM_ROLE", "members": "MEMBER_NAME" }, } }
Where:
IAM_ROLE
is the IAM role you are granting the member. For example,roles/storage.objectViewer
.MEMBER_NAME
is the type and name of the member 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.json \ -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 name of the file 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 member access. For example,my-project
.
Viewing 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 Members: View the Role column associated with individual members to see which roles each member has.
- View by Roles: Use the drop-down associated with individual roles to see which members have the role.
gsutil
Project-level IAM policies are managed through the gcloud
command, which is part of the Google Cloud SDK. 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.
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 member access. For example,my-project
.
Removing a member 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 member.
Make sure you are viewing permissions by Members, and select the members 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, which
is part of the Google Cloud SDK. 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.
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 to which you want to add member 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 member from the policy.
Use
cURL
to call the Resource Manager API with aPOST setIamPolicy
request:curl -X POST --data-binary @JSON_FILE_NAME.json \ -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 name of the file 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 want to grant member 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.