Skip to main content

GRANT A GROUP READ ACCESS TO A CLOUD STORAGE BUCKET

This guide shows you how to give a Google group read access to the objects in an existing Cloud Storage bucket. You add an IAM binding to the bucket, and the bucket's other bindings are kept.

Prerequisites

  • A @swamp/gcp/storage/buckets behavior for the bucket, with name set to the bucket name and project set to its project. This guide uses a behavior named reports-bucket for the bucket acme-reports in the project acme-prod. See Create and Run a Behavior.
  • Google Cloud credentials for a principal that can read and change the bucket's IAM policy, from Application Default Credentials, the GOOGLE_APPLICATION_CREDENTIALS_JSON or GCP_ACCESS_TOKEN environment variable, or a vault
  • The bucket using uniform bucket-level access if you want the binding to cover every object in it

Pull the extension

If the repository does not have the Cloud Storage extension yet, pull it:

swamp extension pull @swamp/gcp/storage

The output looks like:

INF extension·pull: Pulling "@swamp/gcp/storage"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/gcp/storage"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/gcp/storage"@"2026.10.13.1"
INF extension·pull: Extracted 28 files:

Supply credentials from a vault

If the credentials are stored in a vault and not in the environment, point the behavior's credentialsJson global argument at the vault entry:

globalArguments:
  name: acme-reports
  project: acme-prod
  credentialsJson: "${{ vault.get('default', 'gcp-credentials') }}"

If you use a short-lived OAuth2 token, set accessToken the same way. See Auto-Refresh Cloud Credentials to keep that token current.

Add the binding

Run add_iam_binding with the role and the group:

swamp behavior run reports-bucket add_iam_binding \
  --input role=roles/storage.objectViewer \
  --input 'members:json=["group:analysts@example.com"]'

This reads the bucket's current IAM policy, adds group:analysts@example.com to the roles/storage.objectViewer binding, and writes the policy back with its etag, so a change someone else made in the meantime causes a conflict and is not overwritten.

To grant several principals at once, put all of them in the members array. To restrict the grant with an IAM condition, also pass a condition input as JSON with a title and an expression, and an optional description.

Confirm the policy

Read the bucket's IAM policy back:

swamp behavior run reports-bucket get_iam_policy

This fetches the bucket's current IAM policy from Google Cloud. Check that the roles/storage.objectViewer binding lists group:analysts@example.com.

Revoke the access

To remove the group again, run remove_iam_binding with the same role and members inputs. Only the members you list are removed, and anyone else in the binding keeps the role. If you leave out members, the whole binding for that role is removed.

For every method and input of the buckets type, see the Google Cloud Storage extensions reference.