[Usage](https://docs.cloud.google.com/storage/docs/access-control/using-iam-permissions.md.txt)

This page provides an overview of Identity and Access Management (IAM) and its use with
controlling access to the buckets, managed folders, and objects resources in
Cloud Storage.

- To learn about other ways of controlling access in Cloud Storage, see
  [Overview of Access Control](https://docs.cloud.google.com/storage/docs/access-control.md.txt).

- For a detailed discussion of IAM and its features generally,
  see [Identity and Access Management](https://docs.cloud.google.com/iam/docs.md.txt).

## Overview

IAM allows you to control who has access to the
*resources* in your Google Cloud project. Resources include
Cloud Storage buckets, the managed folders within buckets, and objects
stored within buckets, as well as other Google Cloud entities such as
[Compute Engine instances](https://docs.cloud.google.com/compute/docs.md.txt).

*Principals* are the "who" of IAM. Principals can be individual
users, groups, domains, or even the public as a whole. Principals are granted
[*roles*](https://docs.cloud.google.com/storage/docs/access-control/iam.md.txt#roles), which give them the ability to perform actions in
Cloud Storage as well as Google Cloud more generally. Each role
is a collection of one or more [*permissions*](https://docs.cloud.google.com/storage/docs/access-control/iam.md.txt#permissions). Permissions are
the basic units of IAM: each permission lets you perform a
certain action.

For example, the `storage.objects.create` permission lets you create
objects. This permission is found in roles such as Storage Object Creator
(`roles/storage.objectCreator`), which grants the permissions useful for
creating objects in a bucket, and Storage Object Admin
(`roles/storage.objectAdmin`), which grants a wide range of permissions for
working with objects.

The collection of IAM roles that you set on a resource is called
an IAM *policy*. The access granted by these roles apply to both
the resource on which the policy is set and any resources contained within that
resource. For example, you can set an IAM policy on a bucket that
gives a user administrative control of that bucket and its objects. You can also
set an IAM policy on the overall project that gives another user
the ability to view objects in any bucket within that project.

You can also use [IAM deny policies](https://docs.cloud.google.com/iam/docs/deny-overview.md.txt) to deny access to
resources. When a deny policy is attached to a resource, the principal in the
policy can't use the specified permission to access the resource or any
sub-resource within it, regardless of the roles they're granted. Deny policies
override any IAM allow policies.

> [!NOTE]
> **Note:** While you can set IAM policies on buckets, managed folders, and projects in order to control access to objects within them, you cannot set IAM policies directly on individual objects. In addition, you can't set IAM deny policies on buckets, managed folders, or individual objects.

## Permissions

Permissions allow principals to perform specific actions on buckets, managed
folders, or objects in Cloud Storage. For example, the
`storage.buckets.list` permission allows a principal to list the buckets in your
project. You don't directly give principals permissions; instead, you grant
[roles](https://docs.cloud.google.com/storage/docs/access-control/iam.md.txt#roles), which have one or more permissions bundled within them.

For a reference list of the IAM permissions that apply to
Cloud Storage, see
[IAM Permissions for Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/iam-permissions.md.txt).

## Roles

Roles are a bundle of one or more [permissions](https://docs.cloud.google.com/storage/docs/access-control/iam.md.txt#permissions). For example, the
Storage Object Viewer (`roles/storage.objectViewer`) role contains the
permissions `storage.objects.get` and `storage.objects.list`. You grant roles to
principals, which allows them to perform actions on the buckets, managed
folders, and objects in your project.

For a reference list of the IAM roles that apply to
Cloud Storage, see
[IAM Roles for Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/iam-roles.md.txt).

### Granting roles at the project level, bucket level, or managed folder level

You can grant roles to principals at the project level, bucket level, or
managed folder level. The permissions granted by those roles apply additively
throughout the resource hierarchy. You can grant roles at different levels of
the resource hierarchy for more granularity in your permissions model.

For example, say you want to give a user permission to read objects in any
bucket within a project but create objects only in bucket A. To achieve this,
you can give the user the Storage Object Viewer (`roles/storage.objectViewer`)
role for the project, which allows the user to read any object stored in any
bucket within your project, and the Storage Object Creator
(`roles/storage.objectCreator`) role for bucket A, which allows the user to
create objects only in that bucket.

Some roles can be used at all levels of the resource hierarchy. When used
at the project level, the permissions they contain apply to all buckets,
folders, and objects in the project. When used at the bucket level, the
permissions only apply to a specific bucket and the folders and objects within
it. Examples of such roles are the Storage Admin (`roles/storage.admin`) role,
the Storage Object Viewer (`roles/storage.objectViewer`) role, and
the Storage Object Creator (`roles/storage.objectCreator`) role.

Some roles can only be applied at one level. For example, you can only apply the
Storage Legacy Object Owner (`roles/storage.legacyObjectOwner`) role at the
bucket level or at the managed folder level. The [IAM roles](https://docs.cloud.google.com/iam/docs/deny-access.md.txt#required-roles)
that allow you to control IAM deny policies can only be applied
at the [organization](https://docs.cloud.google.com/resource-manager/docs/cloud-platform-resource-hierarchy.md.txt#organizations) level.

> [!CAUTION]
> **Caution:** Setting IAM policies at project, bucket, and managed folder levels potentially allow users access to objects that they did not have previously. Carefully evaluate your policies before setting them.

> [!NOTE]
> **Note:** When you view the IAM policy for a project, you don't see the IAM policies that exist for individual buckets. If you view the IAM policy for an individual bucket using the [Google Cloud console](https://docs.cloud.google.com/storage/docs/cloud-console.md.txt), you do see project-level permissions that apply to that bucket; however, other Cloud Storage tools, such as [`gcloud storage`](https://docs.cloud.google.com/sdk/gcloud/reference/storage.md.txt) and the [Client Libraries](https://docs.cloud.google.com/storage/docs/apis.md.txt) only return the policy of the bucket and don't include information inherited from the project-level policy. Be sure to consult both project and bucket policies when evaluating access levels for principals.

### Relation to ACLs

In addition to IAM, your buckets and objects can use a legacy
access control system called [access control lists (ACLs)](https://docs.cloud.google.com/storage/docs/access-control/lists.md.txt) if the
[uniform bucket-level access](https://docs.cloud.google.com/storage/docs/uniform-bucket-level-access.md.txt) feature is not enabled for your bucket. Generally,
[you should avoid using ACLs](https://docs.cloud.google.com/storage/docs/access-control/lists.md.txt#iam-vs-acl), and you should enable uniform bucket-level access
for your bucket. This section discusses what you should keep in mind if you
allow ACL usage for a bucket and the objects within it.

*Legacy Bucket* IAM roles work in tandem with [bucket ACLs](https://docs.cloud.google.com/storage/docs/access-control/lists.md.txt#permissions):
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 IAM role for the bucket.

| Legacy Bucket role | Equivalent ACL |
|---|---|
| Storage Legacy Bucket Reader (`roles/storage.legacyBucketReader`) | Bucket Reader |
| Storage Legacy Bucket Writer (`roles/storage.legacyBucketWriter`) | Bucket Writer |
| Storage Legacy Bucket Owner (`roles/storage.legacyBucketOwner`) | Bucket Owner |

All other bucket-level IAM roles, including *Legacy Object*
IAM roles, work independently from ACLs. Similarly, all
project-level IAM roles work independently from ACLs. For
example, if you give a user the Storage Object Viewer
(`roles/storage.objectViewer`) role, the ACLs remain unchanged.

Because object ACLs work independently from IAM roles, they don't
appear in the hierarchy of IAM policies. When evaluating who has
access to one of your objects, make sure you [check the ACLs](https://docs.cloud.google.com/storage/docs/access-control/create-manage-lists.md.txt#retrieving-acls) for the
object, in addition to checking your project-level and bucket-level
IAM policies.

#### IAM deny policies versus ACLs

[IAM deny policies](https://docs.cloud.google.com/iam/docs/deny-overview.md.txt) apply to access granted by ACLs. For
example, if you create a deny policy that denies a principal the
`storage.objects.get` permission on a project, the principal cannot view objects
in that project, even if they are granted the `READER` permission to individual
objects.

#### IAM permission for changing ACLs

You can use IAM to give principals 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 want to define your own roles which contain bundles of permissions that
you specify. To support this, IAM offers [custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt).

## Principal types

There are a number of different types of principals. For example,
Google Cloud accounts represent a general type, while
`allAuthenticatedUsers` and `allUsers` are two specialized types. For a list of
principal types in IAM, see [Principal identifiers](https://docs.cloud.google.com/iam/docs/principal-identifiers.md.txt). For
more information about principals in general, see
[IAM principals](https://docs.cloud.google.com/iam/docs/principals-overview.md.txt).

### Convenience values

Cloud Storage supports *convenience values* , which are a special set of
principals that you can reference in your buckets' IAM allow
policies. You should generally avoid using convenience values in production
environments, because they require granting [legacy basic roles](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#legacy-basic), a practice
which is discouraged in production environments.

A convenience value is a two-part identifier consisting of a legacy basic role
and a project ID:

- `projectOwner:PROJECT_ID`
- `projectEditor:PROJECT_ID`
- `projectViewer:PROJECT_ID`

Convenience values let you manage access for principals who have been granted
legacy basic roles. If you grant a role to a convenience value, then you
effectively grant that role to all principals with the specified basic role on
the specified project.

For example, say jane@example.com and john@example.com have the Viewer
(`roles/viewer`) legacy basic role for a project named `my-example-project`, and say
you have a bucket in that project named `my-bucket`. If you grant the Storage
Object Creator (`roles/storage.objectCreator`) role for
`my-bucket` to the convenience value `projectViewer:my-example-project`, then
both jane@example.com and john@example.com gain the permissions associated with
the Storage Object Creator role for `my-bucket`.

You can grant and revoke access to convenience values for your buckets, but note
that Cloud Storage automatically applies them in certain circumstances.
See [modifiable behavior for basic roles in Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/iam-roles.md.txt#basic-roles-modifiable) for more
information.

## Conditions

[IAM Conditions](https://docs.cloud.google.com/iam/docs/conditions-overview.md.txt) lets you set conditions that control
how permissions are granted or denied to principals. Cloud Storage
supports the following types of condition attributes:

- [`resource.name`](https://docs.cloud.google.com/iam/docs/conditions-attribute-reference.md.txt#resourcename_attribute): Grant or deny access to buckets and objects based
  on the bucket or object name. You can also use [`resource.type`](https://docs.cloud.google.com/iam/docs/conditions-attribute-reference.md.txt#resourcetype_attribute) to
  grant access to either buckets or objects, but doing so is mostly redundant
  with using `resource.name`. The following example condition applies an
  IAM setting to all objects with the same prefix:

  ```
  resource.name.startsWith('projects/_/buckets/BUCKET_NAME/objects/OBJECT_PREFIX')
  ```

  <br />

- [Date/time](https://docs.cloud.google.com/iam/docs/conditions-attribute-reference.md.txt#date-time): Set an expiration date for the permission.

  ```
  request.time < timestamp('2019-01-01T00:00:00Z')
  ```

  <br />

These conditional expressions are logic statements that use a subset of the
[Common Expression Language](https://github.com/google/cel-spec) (CEL). You specify conditions in
the role bindings of a bucket's IAM policy.

> [!NOTE]
> **Note:** You can also use double quotes in your conditional expressions, but they should be properly escaped when you are using Google Cloud CLI commands and HTTP/REST requests to update a conditional policy. For example, `request.time < timestamp(\"2019-01-01T00:00:00Z\")`.

Keep these restrictions in mind:

- You must enable [uniform bucket-level access](https://docs.cloud.google.com/storage/docs/uniform-bucket-level-access.md.txt) on a bucket before adding conditions at the bucket level. Although conditions are allowed at the project level, you should migrate all buckets in the project to uniform bucket-level access to prevent Cloud Storage ACLs from overriding project-level IAM conditions. You can apply a [uniform bucket-level access constraint](https://docs.cloud.google.com/storage/docs/org-policy-constraints.md.txt#uniform-access) to enable uniform bucket-level access for all new buckets in your project.
- Managed folders can be specified as a resource in IAM allow policy conditions. Managed folders can't be specified as a resource in IAM deny policy conditions. IAM deny policy conditions can only be set by using tags, and tags don't support managed folders.
- IAM deny policies can only be applied to project, folder, and organization resources. They can't be applied to buckets or managed folders.
- When using the JSON API to call [`getIamPolicy`](https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/getIamPolicy.md.txt) and [`setIamPolicy`](https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy.md.txt) on buckets with conditions, you must set the [IAM policy version](https://docs.cloud.google.com/iam/docs/allow-policies.md.txt#versions) to 3.
- Since the `storage.objects.list` permission is granted at the bucket level, you cannot use the `resource.name` condition attribute to restrict object listing access to a subset of objects in the bucket.
- Expired conditions remain in your IAM policy until you remove them.

## Using with Cloud Storage tools

Although IAM permissions cannot 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 on which IAM permissions allow users to perform
actions with different Cloud Storage tools, see
[IAM references for Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/iam-reference.md.txt).

## What's next

- [Learn how to use IAM with Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/using-iam-permissions.md.txt).
- [Review the IAM reference table for Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/iam-reference.md.txt).
- Learn about [best practices for using IAM](https://docs.cloud.google.com/storage/docs/access-control.md.txt#best-practices).
- [Manage IAM policies](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt) for all of your Google Cloud resources.