Set and manage IAM policies on managed folders

This page describes how to set Identity and Access Management (IAM) policies on managed folders, so you can get fine-grained access control over specific groups of objects within a bucket.

If you're looking for other methods of access control, see the following resources:

To learn about how to control access to whole buckets and the objects within them, see Set and manage IAM policies on buckets.
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 managed folders, ask your administrator to grant you the Storage Folder Admin (roles/storage.folderAdmin) IAM role for the bucket that contains the managed folders.

This role contain the following permissions, which are required to set and manage IAM policies for managed folders:

storage.managedFolders.getIamPolicy
storage.managedFolders.setIamPolicy

You can also get these permissions with custom roles.

For information about granting roles for buckets, see Set and manage IAM policies on buckets.

Set an IAM policy on a managed folder

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket that contains the managed folder you want to set an IAM policy on.
In the Bucket details page, click the More options icon in the Folder browser pane next to the managed folder you want to set an IAM policy on.

If you want to control access within a folder or a simulated folder, follow the steps in Create a managed folder to enable management on the folder or simulated folder.
Click Edit access.
In the Permissions for MANAGED_FOLDER_NAME pane, click Add principal .
In the New principals field, enter the principal for which you want to grant access. For more information about principals you can include, see Principal identifiers.
In the Assign roles section, use the Select a role drop-down to specify the level of access you want to grant to the principal.
Click Save.

Command line

You can grant access to a managed folder by using either of the following commands:

gcloud storage managed-folders add-iam-policy-binding: adds a single role binding for a principal to the existing IAM policy of the managed folder. Bindings that already exist in the policy remain unchanged. You don't need to create a policy file to use this command.
gcloud storage managed-folders set-iam-policy: replaces the entire IAM policy of the managed folder with the policy that you define in a JSON file. Any bindings that aren't included in the JSON file are removed from the managed folder.

To add a role binding to the IAM policy of a managed folder, run the gcloud storage managed-folders add-iam-policy-binding command:

gcloud storage managed-folders add-iam-policy-binding gs://BUCKET_NAME/MANAGED_FOLDER_NAME --member=PRINCIPAL_IDENTIFIER --role=IAM_ROLE

Replace the following:

BUCKET_NAME: the name of the bucket that contains the managed folder to which you want to grant the principal access—for example, my-bucket.
MANAGED_FOLDER_NAME: the name of the managed folder to which you want to grant the principal access—for example, my-managed-folder/.
PRINCIPAL_IDENTIFIER: the principal who you are granting managed folder access to—for example, user:example-service-account@example-project.. For a list of principal identifier formats, see Principal identifiers.
IAM_ROLE: the IAM role you are granting—for example, roles/storage.objectViewer.

To include an IAM condition in the role binding, see Set a new condition on a managed folder.

To replace the entire IAM policy of a managed folder, complete the following steps:

Create a JSON file that contains the following information:
```
{
  "bindings":[
    {
      "role": "IAM_ROLE",
      "members":[
        "PRINCIPAL_IDENTIFIER"
      ]
    }
  ]
}
```
Replace the following:
- IAM_ROLE: the IAM role you are granting—for example, roles/storage.objectViewer.
- PRINCIPAL_IDENTIFIER: the principal who you are granting managed folder access to—for example, user:example-service-account@example-project.. For a list of principal identifier formats, see Principal identifiers.
Include every binding that you want the managed folder to have, because the bindings in this file replace all existing bindings.
Use the gcloud storage managed-folders set-iam-policy command:
```
gcloud storage managed-folders set-iam-policy gs://BUCKET_NAME/MANAGED_FOLDER_NAME POLICY_FILE
```
Replace the following:
- BUCKET_NAME: the name of the bucket that contains the managed folder to which you want to apply the IAM policy—for example, my-bucket.
- MANAGED_FOLDER_NAME: the name of the managed folder to which you want to apply the IAM policy—for example, my-managed-folder/.
- POLICY_FILE: the path to the JSON file you created in step 1.

REST APIs

JSON

Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
Create a JSON file that contains the following information:
```
{
  "bindings":[
    {
      "role": "IAM_ROLE",
      "members":[
        "PRINCIPAL_IDENTIFIER"
      ]
    }
  ]
}
```
Replace the following:
- IAM_ROLE: the IAM role you are granting—for example, roles/storage.objectViewer.
- PRINCIPAL_IDENTIFIER: the principal who you are granting managed folder access to—for example, user:example-service-account@example-project.. For a list of principal identifier formats, see Principal identifiers.
Use cURL to call the JSON API with a PUT setIamPolicy request:
```
curl -X PUT --data-binary @POLICY_FILE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage./storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAME/iam"
```
Replace the following:
- POLICY_FILE: the path to the JSON policy file that you created in the previous step.
- BUCKET_NAME: the name of the bucket that contains the managed folder to which you want to apply the IAM policy—for example, my-bucket.
- MANAGED_FOLDER_NAME: the name of the managed folder to which you want to give the principal access—for example, my-managed-folder/.

View the IAM policy for a managed folder

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket that contains the managed folder for which you want to view IAM policies.
In the Bucket details page, click the More options icon in the Folder browser pane next to the managed folder for which you want to view the IAM policy.
Click Edit access.

The Permissions for FOLDER_NAME pane displays the permissions on the managed folder, including the principal, role, inherited roles, and IAM conditions.

Command line

Use the gcloud storage managed-folder get-iam-policy command:

gcloud storage managed-folders get-iam-policy gs://BUCKET_NAME/MANAGED_FOLDER_NAME

Replace the following:

BUCKET_NAME: the name of the bucket that contains the managed folder whose IAM policy you want to view—for example, my-bucket.
MANAGED_FOLDER_NAME: the name of the managed folder whose IAM policy you want to view—for example, my-managed-folder/.

REST APIs

JSON

Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
Use cURL to call the JSON API with a GET getIamPolicy request:
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage./storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAME/iam"
```
Replace the following:
- BUCKET_NAME: the name of the bucket that contains the managed folder whose IAM policy you want to view—for example, my-bucket.
- MANAGED_FOLDER_NAME: the name of the managed folder whose IAM policy you want to view—for example, my-managed-folder/.

Remove a principal from a managed folder policy

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket that contains the managed folder for which you want to view IAM policies.
In the Bucket details page, click the More options icon in the Folder browser pane next to the managed folder for which you want to remove a principal.
Click Edit access.
In the Permissions for FOLDER_NAME pane, enter the name of the principal in the Filter field.
Click the Delete icon to delete the principal.

Cloud Storage deletes the principal from your managed folder.

Command line

Use the gcloud storage managed-folder remove-iam-policy-binding command:

gcloud storage managed-folders remove-iam-policy-binding  gs://BUCKET_NAME/MANAGED_FOLDER_NAME --member=PRINCIPAL_IDENTIFIER --role=IAM_ROLE

Replace the following:

BUCKET_NAME: the name of the bucket that contains the managed folder you are revoking access to—for example, my-bucket.
MANAGED_FOLDER_NAME: the name of the managed folder whose IAM policy you want to remove—for example, my-managed-folder/.
PRINCIPAL_IDENTIFIER: the principal who you are revoking access from—for example, user:example-service-account@example-project.. For a list of principal identifier formats, see Principal identifiers.
IAM_ROLE: the IAM role you are revoking—for example, roles/storage.objectViewer.

REST APIs

JSON

Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
Get the existing policy applied to your managed folder. To do so, use cURL to call the JSON API with a GET getIamPolicy request:
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage./storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAME/iam"
```
Replace the following:
- BUCKET_NAME: the name of the bucket that contains the managed folder you are revoking access to—for example, my-bucket.
- MANAGED_FOLDER_NAME: the name of the managed folder whose IAM policy you want to remove—for example, my-managed-folder/.
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 a PUT 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./storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAME/iam"
```
Replace the following:
- JSON_FILE_NAME: the path for the file that you created in Step 3.
- BUCKET_NAME: the name of the bucket that contains the managed folder you are revoking access to—for example, my-bucket.
- MANAGED_FOLDER_NAME: the name of the managed folder whose IAM policy you want to remove—for example, my-managed-folder/.

Use IAM Conditions on managed folders

The following sections show you how to add and remove IAM Conditions on your managed folders. To view the IAM Conditions for your managed folders, see Viewing the IAM policy for a managed folder. For more information about using IAM Conditions with Cloud Storage, see Conditions.

Managed folders can be specified as a resource in IAM allow policy conditions, but they can't be specified as a resource in IAM deny policy conditions. Denial conditions only recognize resource tag functions, and tags can't be attached to managed folders.

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

Set a new condition on a managed folder

Command line

Create a JSON or YAML file that defines the condition, including the title of the condition, the attribute-based logic expression 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 the expression.
Use the gcloud storage managed-folders add-iam-policy-binding command with the --condition-from-file flag:

gcloud storage managed-folders add-iam-policy-binding  gs://BUCKET_NAME/MANAGED_FOLDER_NAME --member=PRINCIPAL_IDENTIFIER --role=IAM_ROLE --condition-from-file=CONDITION_FILE

Replace the following:

BUCKET_NAME: the name of the bucket that contains the managed folder to which you are granting the principal access—for example, my-bucket.
MANAGED_FOLDER_NAME: the name of the managed folder to which you are granting the principal access—for example, my-managed-folder/.
PRINCIPAL_IDENTIFIER: the principal who the condition applies to—for example, user:example-service-account@example-project.. For a list of principal identifier formats, see Principal identifiers.
IAM_ROLE: the IAM role you are granting to the principal—for example, roles/storage.objectViewer.
CONDITION_FILE: 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.

REST APIs

JSON

Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
Use a GET getIamPolicy request to save the managed folder's IAM policy to a temporary JSON file:
```
curl \
'https://storage./storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAMEiam' \
--header 'Authorization: Bearer $(gcloud auth print-access-token)' > tmp-policy.json
```
Replace the following:
- BUCKET_NAME: the name of the bucket that contains the managed folder you want to set an IAM Condition on.
- MANAGED_FOLDER_NAME: the name of the managed folder you want to set an IAM Condition on.
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"
}
```
Replace the following:
- VERSION: the IAM policy version, which is required to be 3 for managed folders with IAM Conditions.
- IAM_ROLE: the role to which the condition applies—for example, roles/storage.objectViewer.
- PRINCIPAL_IDENTIFIER: the principal who the condition applies to—for example, user:example-service-account@example-project.. For a list of principal identifier formats, see Principal identifiers.
- TITLE: the title of the condition—for example, expires in 2019.
- DESCRIPTION: an optional description of the condition—for example, Permission revoked on New Year's.
- EXPRESSION: 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. Cloud Storage only supports the date/time, resource type, and resource name attributes.
Don't 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 $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storage./storage/v1/b/BUCKET_NAME/managedFoldersMANAGED_FOLDER_NAME/iam"
```
Replace the following:
- BUCKET_NAME: the name of the bucket that contains the managed folder you want to set an IAM Condition on.
- MANAGED_FOLDER_NAME: the name of the managed folder you want to set an IAM Condition on.

Remove a condition from a managed folder

Command line

Use the gcloud storage managed-folders get-iam-policy command to save the managed folder's IAM policy to a temporary JSON file.
```
gcloud storage managed-folders get-iam-policy gs://BUCKET_NAME/MANAGED_FOLDER_NAME > tmp-policy.json
```
Edit the tmp-policy.json file in a text editor to remove conditions from the IAM policy.
Use the gcloud storage managed-folders set-iam-policy command to set the modified IAM policy on the managed folder.
```
gcloud storage managed-folders set-iam-policy gs://BUCKET_NAME/MANAGED_FOLDER_NAME tmp-policy.json
```

REST APIs

JSON

Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
Use a GET getIamPolicy request to save the managed folder's IAM policy to a temporary JSON file:
```
curl \
'https://storage./storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAMEiam' \
--header 'Authorization: Bearer $(gcloud auth print-access-token)' > tmp-policy.json
```
Replace the following:
- BUCKET_NAME: the name of the bucket that contains the managed folder you are changing access to—for example, my-bucket.
- MANAGED_FOLDER_NAME: the name of the managed folder you are changing access to—for example, my-managed-folder/.
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 managed folder:
```
curl -X PUT --data-binary @tmp-policy.json \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storage./storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAMEiam"
```
Replace the following:
- BUCKET_NAME: the name of the bucket that contains the managed folder you are changing access to—for example, my-bucket.
- MANAGED_FOLDER_NAME: the name of the managed folder you are changing access to—for example, my-managed-folder/.

Use IAM with projects

See Manage access to projects, managed folders, and organizations for guides about granting and revoking IAM roles at the project level and above.

Best practices

You should set the minimum role possible that gives the principal the required access. For example, if a team member only needs to view the managed folders in a bucket, grant them the Storage Object Admin (roles/storage.objectAdmin) role instead of the Storage Folder Admin (roles/storage.folderAdmin) role. Similarly, if the team member needs full control of the managed folders in a bucket, grant them the Storage Folder Admin (roles/storage.folderAdmin) 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.
To troubleshoot failed operations related to IAM roles and permissions, see Troubleshooting.

Set and manage IAM policies on managed folders Stay organized with collections Save and categorize content based on your preferences.

Required roles

Set an IAM policy on a managed folder

Console

Command line

REST APIs

JSON

View the IAM policy for a managed folder

Console

Command line

REST APIs

JSON

Remove a principal from a managed folder policy

Console

Command line

REST APIs

JSON

Use IAM Conditions on managed folders

Set a new condition on a managed folder

Command line

REST APIs

JSON

Remove a condition from a managed folder

Command line

REST APIs

JSON

Use IAM with projects

Best practices

What's next

Set and manage IAM policies on managed folders