Identity and Access Management

This page provides an overview of Identity and Access Management (IAM) and its use with controlling access to buckets and objects in Google Cloud Storage. To learn how to set and manage IAM permissions for Cloud Storage buckets and projects, see Using IAM Permissions. To learn about other ways of controlling access to buckets and objects, see Overview of Access Control.

This page focuses on aspects of IAM that are relevant specifically to Cloud Storage. For a detailed discussion of IAM and its features generally, see the Google Cloud Identity and Access Management developer's guide. In particular, see the Managing IAM Policies section.

Overview

Google Cloud Identity and Access Management (IAM) allows you to control who has access to the resources in your Google Cloud Platform project. Resources include Cloud Storage buckets and objects stored within buckets, as well as other Cloud Platform entities such as Google Compute Engine instances.

The set of access rules you apply to a resource is called an IAM policy. An IAM policy applied to your project defines the actions that users can take on all objects or buckets within your project. An IAM policy applied to a single bucket defines the actions that users can take on that specific bucket and objects within it.

For example, you can create an IAM policy for one of your buckets that gives one user administrative control of that bucket. Meanwhile, you can add another user to your project-wide IAM policy that gives that user the ability to view objects in any bucket of your project.

Members are the "who" of IAM. Members can be individual users, groups, domains, or even the public as a whole. Members are assigned roles, which grant members the ability to perform actions in Cloud Storage as well as Cloud Platform more generally. Each role is a collection of one or more permissions. Permissions are the basic units of IAM: each permission allows you to perform a certain action.

For example, the storage.objects.create permission allows you to create objects. This permission is found in roles such as roles/storage.objectCreator, where it is the only permission, and roles/storage.objectAdmin, where many permissions are bundled together. If you give the roles/storage.objectCreator role to a member for a specific bucket, they can only create objects in that bucket. If you give another member the roles/storage.objectAdmin role for the bucket, they can do additional tasks, such as deleting objects, but still only within that bucket. If these two users are assigned these roles and no others, they won't have knowledge of any other buckets in your project. If you give a third member the roles/storage.objectAdmin role, but do so for your project and not just a single bucket, they have access to any object in any bucket of your project.

Using Cloud Storage IAM makes it easy to limit a member's permissions without having to modify each bucket or object permission individually.

Permissions

Permissions allow members to perform specific actions on buckets or objects in Cloud Storage. For example, the storage.buckets.list permission allows a member to list the buckets in your project. You don't directly give members permissions; instead, you assign roles, which have one or more permissions bundled within them.

For a reference list of the IAM permissions that apply to Cloud Storage, see Cloud Storage IAM Permissions.

Roles

Roles are a bundle of one or more permissions. For example, roles/storage.objectViewer contains the permissions storage.objects.get and storage.objects.list. You assign roles to members, which allows them to perform actions on the buckets and objects in your project.

For a reference list of the IAM roles that apply to Cloud Storage, see Cloud Storage IAM Roles.

Project-level roles vs. bucket-level roles

Granting roles at the bucket level does not affect any existing roles that you granted at the project level, and vice versa. Thus, you can use these two levels of granularity to customize your permissions. For example, say you want to give a user permission to read objects in any bucket but create objects only in one specific bucket. To achieve this, give the user the roles/storage.objectViewer role at the project level, thus allowing the user to read any object stored in any bucket in your project, and give the user roles/storage.objectCreator role at the bucket level for a specific bucket, thus allowing the user to create objects only in that bucket.

Some roles can be used at both the project level and the bucket level. When used at the project level, the permissions they contain apply to all buckets and objects in the project. When used at the bucket level, the permissions only apply to a specific bucket and the objects within it. Examples of such roles are roles/storage.admin, roles/storage.objectViewer, and roles/storage.objectCreator.

Some roles can only be applied at one level. For example, you can only apply the Viewer role at the project level, while you can only apply the roles/storage.legacyObjectOwner role at the bucket level.

Relation to ACLs

Legacy Bucket IAM roles work in tandem with bucket ACLs: when you add or remove a Legacy Bucket role, the ACLs associated with the bucket reflect your changes. Similarly, changing a bucket-specific ACL updates the corresponding Legacy Bucket role for the bucket.

Legacy Bucket role Equivalent ACL
roles/storage.legacyBucketReader Bucket Reader
roles/storage.legacyBucketWriter Bucket Writer
roles/storage.legacyBucketOwner Bucket Owner

All other bucket-level IAM roles, and all project-level IAM roles, work independently from ACLs. For example, if you give a user the Storage Object Viewer role, the ACLs remain unchanged. This means you can use bucket-level IAM roles to grant broad access to all objects within a bucket and use the fine-grained object ACLs to customize access to specific objects within the bucket.

IAM permission for changing ACLs

You can use IAM to grant members the permission needed to change ACLs on objects. The following storage.buckets permissions together allow users to work with bucket ACLs and default object ACLs: .get, .getIamPolicy, .setIamPolicy, and .update.

Similarly, the following storage.objects permissions together allow users to work with object ACLs: .get, .getIamPolicy, .setIamPolicy, and .update.

Custom roles

While IAM has many predefined roles that cover common use cases, you may wish to define your own roles which contain bundles of permissions that you specify. To support this, IAM offers custom roles.

Member types

There are a number of different types of members. For example, Google accounts and Google groups represent two general types, while allAuthenticatedUsers and allUsers are two specialized type. For a list of typical member types in IAM, see Concepts related to identity. In addition to the types listed there, IAM supports the following member types, which can be applied specifically to your Cloud Storage bucket IAM policies:

  • projectOwner:[PROJECT_ID]
  • projectEditor:[PROJECT_ID]
  • projectViewer:[PROJECT_ID]

Where [PROJECT_ID] is the ID of a specific project.

When you grant one of the above member types a role, all members with the specified permission for the specified project get the role you select. For example, say you want to give all members who have the Viewer role for the project my-example-project the roles/storage.objectCreator role for one of your buckets. To do so, give the member projectViewer:my-example-project the roles/storage.objectCreator role for that bucket.

Using with Cloud Storage tools

Although IAM permissions can't be set through the XML API, users granted IAM permissions can still use the XML API, as well as any other tool for accessing Cloud Storage.

For references of which IAM permissions allow users to perform actions with different Cloud Storage tools, see IAM with the Cloud Console, IAM with gsutil, IAM with JSON, and IAM with XML.

Best practices

IAM, like any other administrative settings, requires active management to be effective. Before you make a bucket or object accessible to other users, be sure you know who you want to share the bucket or object with and what roles you want each of those people to play. Over time, changes in project management, usage patterns, and organizational ownership may require you to modify IAM settings on buckets and projects, especially if you manage Cloud Storage in a large organization or for a large group of users. As you evaluate and plan your access control settings, keep the following best practices in mind:

  • Use the principle of least privilege when granting access.

    The principle of least privilege is a security guideline for granting privileges or rights. When you grant access based on the principle of least privilege, you grant the minimum privilege that's necessary for a user to accomplish their assigned task. For example, if you want to share a file with someone, grant them the storage.objectReader role and not the storage.admin role.

  • Avoid granting roles with setIamPolicy permission to people you do not know.

    Granting setIamPolicy permission allows a user to change permissions and take control of data. You should use roles with setIamPolicy permission only when you want to delegate administrative control over objects and buckets.

  • Be careful how you grant permissions for anonymous users.

    The allUsers and allAuthenticatedUsers member types should only be used when it is acceptable for anyone on the Internet to read and analyze your data. While these scopes are useful for some applications and scenarios, it is usually not a good idea to grant all users certain permissions such as setIamPolicy, update, create, or delete.

  • Understand the Viewer/Editor/Owner project roles in Cloud Storage

    The Viewer/Editor/Owner project-level roles effectively grant the access their names imply within Cloud Storage; however they do so indirectly through additional access that is provided at the bucket and object levels, using member types unique to Cloud Storage. While the access is added by default, you can revoke it.

    For example, the Viewer role, by itself, only gives a member storage.buckets.list permission, but new buckets, by default, grant the roles/storage.legacyBucketReader role to all members with the Viewer role for the project. This bucket role is what allows a Viewer to view a bucket. Additionally, the bucket has a default object ACL of projectPrivate, which means objects added to the bucket gain, by default, the projectPrivate ACL. This ACL is what allows a Viewer to view the object.

    Similarly, the Editor and Owner project roles have limited Cloud Storage access by themselves, but members assigned these roles gain roles/storage.legacyBucketOwner for new buckets, and ownership of objects through the projectPrivate ACL.

    Note that because some bucket and object access is not inherent to the Viewer/Editor/Owner project roles, it is possible to revoke access that members might otherwise expect they have.

  • Avoid setting permissions that result in inaccessible objects.

    An inaccessible object is an object that cannot be downloaded (read) and can only be deleted. This can happen when the owner of an object leaves a project and there are no bucket or project-level IAM policies that grant access to objects. If this occurs, you can regain access to the object by assigning an appropriate role, such as roles/storage.objectAdmin, to yourself or another member. Note that doing so provides access to all objects in the bucket or project.

  • Be sure you delegate administrative control of your buckets.

    By default, members with the project-level Owner role are the only entities that have the roles/legacyBucketOwner role on a newly created bucket. You should have at least two members with the Owner role at any given time so that if a team member leaves the group, your buckets can still be managed by the other members.

What's next

Send feedback about...

Cloud Storage Documentation