Configure access to a source: Cloud Storage

Storage Transfer Service can use a Cloud Storage source bucket in two transfer types:

Agentless transfers: Cloud-to-cloud transfers such as Cloud Storage to Cloud Storage, Cloud Storage to AWS S3, or Cloud Storage to Azure Blob Storage. Permissions are granted to the Storage Transfer Service service agent.
Agent-driven transfers: Transfers involving file systems or on-premises storage that use transfer agents and agent pools. Permissions must be granted to both the service agent and the transfer agent account.

Auto-granting permissions in the Google Cloud console

If you're using the Google Cloud console to create an agentless transfer and have the required user permissions, the service agent will automatically be granted the required permissions on your source bucket.

You can skip the steps on this page. If required, configure access to your destination, then create a transfer.

Prerequisites

User account permissions: To grant the required IAM roles listed on this page, your user account (or user-managed service account) must have permissions to modify IAM policies on your source bucket and agent pool project. For details on user account requirements, see User account permissions.
Agent-based transfer project permissions: For agent-driven transfers, ensure you have configured the required project-level roles for your service agent and transfer agent account. See Agent-based project-level permissions.

Find the service agent's email

The service agent is created automatically when you first create a transfer job, run gcloud transfer setup commands, visit the Storage Transfer page in the Google Cloud console, or call googleServiceAccounts.get.

To obtain the service agent's email, which is used to identify it in Storage Transfer Service commands:

Go to the googleServiceAccounts.get reference page. An interactive panel opens, titled Try this method.
In the panel, under Request parameters, enter your project ID.
Click Execute.

Copy the value of accountEmail. It uses the format: project-PROJECT_NUMBER@storage-transfer-service..

Grant the required permissions

Select your transfer type to view the steps for granting access.

Agentless transfer

The following predefined roles grant the required permissions on the source bucket to the service agent:

Storage Legacy Bucket Reader (roles/storage.legacyBucketReader)
Plus one of the following:
- Storage Object Viewer (roles/storage.objectViewer) if source objects are retained.
- Storage Object User (roles/storage.objectUser) if deleting source objects after transfer (deleteObjectsFromSourceAfterTransfer).
- Storage Object Admin (roles/storage.objectAdmin) if preserving object ACLs (ACL_PRESERVE). Also supports deleting source objects after transfer.

Add the service agent to the source bucket IAM policy:

Console

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

Go to Buckets
Click the Bucket overflow menu () for the source bucket.
Choose Edit access.
Click + Add principal.
In New principals, enter your service agent email.
Select Storage Legacy Bucket Reader from the Select a role drop-down menu.
Click Add another role and select one of the following:
- Storage Object Viewer
- Storage Object User
- Storage Object Admin
Click Save.

gcloud

Run the following gcloud storage commands:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:SERVICE_AGENT_EMAIL --role=roles/storage.legacyBucketReader

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:SERVICE_AGENT_EMAIL --role=roles/storage.OBJECT_ROLE

Replace:

BUCKET_NAME: The name of your source bucket.
SERVICE_AGENT_EMAIL: The service agent email.
OBJECT_ROLE: Choose one of the following based on your transfer options:
objectViewer: If retaining source objects.
objectUser: If deleting source objects after transfer.
objectAdmin: If preserving object ACLs. Also supports deleting source objects after transfer.

REST API

Generate an access token to authenticate your request. If you are using the gcloud CLI, run:
```
gcloud auth print-access-token
```
Retrieve the existing bucket IAM policy (GET https://storage./storage/v1/b/<var>BUCKET_NAME</var>/iam), append the following bindings to its bindings array, and save the merged policy as source_policy.json:
```
{
"bindings": [
  {
    "role": "roles/storage.legacyBucketReader",
    "members": ["serviceAccount:SERVICE_AGENT_EMAIL"]
  },
  {
    "role": "roles/storage.OBJECT_ROLE",
    "members": ["serviceAccount:SERVICE_AGENT_EMAIL"]
  }
]
}
```
Replace:
- SERVICE_AGENT_EMAIL: The service agent email.
- OBJECT_ROLE: Choose objectViewer if retaining source objects, objectUser if deleting source objects, or objectAdmin if preserving object ACLs.

Submit a PUT request using curl:

curl -X PUT --data-binary @source_policy.json \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: application/json" \
  "https://storage./storage/v1/b/BUCKET_NAME/iam"

Replace:

OAUTH2_TOKEN: The OAuth 2.0 access token generated in step 1.
BUCKET_NAME: The name of your source bucket.

Agent-driven transfer

The following predefined roles grant the required access on the source bucket to the service agent:

Storage Legacy Bucket Reader (roles/storage.legacyBucketReader)
Storage Object Creator (roles/storage.objectCreator)

The following role grants the required access on the source bucket to the transfer agent account:

Storage Object Viewer (roles/storage.objectViewer) if retaining source objects, or Storage Object User (roles/storage.objectUser) if deleting source objects after transfer.

Grant these roles on the source bucket.

Console

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

Go to Buckets
Click the Bucket overflow menu () for the source bucket and select Edit access.
Click + Add principal.
In New principals, enter your service agent email.
Select Storage Legacy Bucket Reader and Storage Object Creator from the Select a role drop-down menus.
Click + Add principal again.
Enter your transfer agent account email. This is the user or service account used when installing transfer agents. For example, my-agent-sa@PROJECT_ID. or user@example.com.
Select Storage Object Viewer if retaining source objects, or Storage Object User if deleting source objects after transfer.
Click Save.

gcloud

Grant bucket metadata read and transfer log write roles to the service agent:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:SERVICE_AGENT_EMAIL --role=roles/storage.legacyBucketReader

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:SERVICE_AGENT_EMAIL --role=roles/storage.objectCreator

Grant object access roles to the transfer agent account:
```
gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount_OR_user:TRANSFER_AGENT_ACCOUNT --role=roles/storage.OBJECT_ROLE
```
Replace:
- BUCKET_NAME: The name of your source bucket.
- SERVICE_AGENT_EMAIL: The service agent email.
- serviceAccount_OR_user: Specify either serviceAccount if your transfer agent account is a service account, or user if your agents were installed with a user account.
- TRANSFER_AGENT_ACCOUNT: The email of the account that installed your transfer agents. For example, my-agent-sa@PROJECT_ID. or user@example.com.
- OBJECT_ROLE: Specify objectViewer if retaining source objects, or objectUser if deleting source objects after transfer.

REST API

Generate an access token to authenticate your request. If you are using the gcloud CLI, run:
```
gcloud auth print-access-token
```
Retrieve the existing bucket IAM policy (GET https://storage./storage/v1/b/<var>BUCKET_NAME</var>/iam), append the following bindings to its bindings array, and save the merged policy as agent_source_policy.json:
```
{
  "bindings": [
    {
      "role": "roles/storage.legacyBucketReader",
      "members": ["serviceAccount:SERVICE_AGENT_EMAIL"]
    },
    {
      "role": "roles/storage.objectCreator",
      "members": ["serviceAccount:SERVICE_AGENT_EMAIL"]
    },
    {
      "role": "roles/storage.OBJECT_ROLE",
      "members": ["serviceAccount_OR_user:TRANSFER_AGENT_ACCOUNT"]
    }
  ]
}
```
Replace:
- SERVICE_AGENT_EMAIL: The service agent email.
- serviceAccount_OR_user: Specify either serviceAccount if your transfer agent account is a service account, or user if your agents were installed with a user account.
- TRANSFER_AGENT_ACCOUNT: The email of the account that installed your transfer agents. For example, my-agent-sa@PROJECT_ID. or user@example.com.
- OBJECT_ROLE: Specify objectViewer if retaining source objects, or objectUser if deleting source objects after transfer.

Update the bucket policy via curl:

curl -X PUT --data-binary @agent_source_policy.json \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://storage./storage/v1/b/BUCKET_NAME/iam"

Replace:

OAUTH2_TOKEN: The OAuth 2.0 access token generated in step 1.
BUCKET_NAME: The name of your source bucket.

Cross-project Cloud Storage transfers

To transfer objects between Cloud Storage buckets in different Google Cloud projects, you must grant permissions to the service agent of the project creating the transfer on both the source bucket and the destination bucket.

The user account or user-managed service account creating the transfer only needs permissions on the project from which the transfer job is created.

To grant roles for cross-project transfers:

Obtain the service agent email for the project that will run the transfer. See Find the service agent's email.
On the source bucket, grant the following roles to that service agent:
- Storage Legacy Bucket Reader (roles/storage.legacyBucketReader)
- Plus one of the following object roles:
  - Storage Object Viewer (roles/storage.objectViewer) if retaining source objects.
  - Storage Object User (roles/storage.objectUser) if deleting source objects after transfer (deleteObjectsFromSourceAfterTransfer).
  - Storage Object Admin (roles/storage.objectAdmin) if preserving object ACLs (ACL_PRESERVE). Also supports deleting source objects after transfer.
On the destination bucket, grant the following roles to the same service agent:
- Storage Legacy Bucket Reader (roles/storage.legacyBucketReader)
- Storage Object User (roles/storage.objectUser), or Storage Object Admin (roles/storage.objectAdmin) if preserving object ACLs (ACL_PRESERVE).

For step-by-step instructions on granting destination bucket access, see Configure access to a sink: Cloud Storage.

Organizational restrictions

If your organization has applied Organization Policy constraints, ensure they permit cross-project service agent access:

Domain restricted sharing (constraints/iam.allowedPolicyMemberDomains): The policy on the project hosting the bucket must permit member domains containing the service agent. See Restricting domains.
Disabling cross-project service account usage (constraints/iam.disableCrossProjectServiceAccountUsage): Ensure this constraint does not block cross-project service account access. See Restricting service accounts.
VPC Service Controls: If buckets belong to different service perimeters, configure ingress and egress rules to allow transfer communication. See Configure VPC Service Controls for cloud object storage transfers.

Fine-grained permissions reference

Select your transfer type to view required roles and permissions.

Agentless transfer

For agentless transfers, permissions must be granted to the Storage Transfer Service service agent:

Permission	Description
`storage.buckets.get`	Allows the service agent to get the location of the bucket.
`storage.objects.list`	Allows the service agent to list objects in the bucket.
`storage.objects.get`	Allows the service agent to read objects in the bucket.
`storage.objects.delete`	Allows the service agent to delete objects in the bucket. Required if `deleteObjectsFromSourceAfterTransfer` is `true`.
`storage.objects.getIamPolicy`	Allows reading ACLs on source objects. Required if object ACL preservation (`ACL_PRESERVE`) is enabled.
`storage.folders.list` `storage.folders.get`	Allows listing and reading folders. Required when transferring from a bucket with hierarchical namespace enabled.

Agent-driven transfer

For agent-driven transfers from a Cloud Storage source, permissions are split between two principals:

Service agent: Requires bucket-level read access to resolve bucket metadata and location, plus object creation access to write agent transfer logs.
Transfer agent account: The service account or user account used to create the transfer agents.

Service agent permissions

Permission	Description
`storage.buckets.get`	Allows the service agent to inspect bucket metadata and location.
`storage.objects.create`	Allows the service agent to write agent transfer logs to the source bucket when transferring from Cloud Storage to a file system.

Transfer agent account permissions

Permission	Description
`storage.objects.list`	Allows agents to list objects in the source bucket.
`storage.objects.get`	Allows agents to read objects from the source bucket.
`storage.objects.delete`	Allows agents to delete source objects if `deleteObjectsFromSourceAfterTransfer` is enabled.
`storage.folders.list` `storage.folders.get`	Allows agents to list and read folders when transferring from a bucket with hierarchical namespace enabled.

What's next

You must configure access to your destination:

Configure access to a source: Cloud Storage Stay organized with collections Save and categorize content based on your preferences.

Auto-granting permissions in the Google Cloud console

Prerequisites

Find the service agent's email

Grant the required permissions

Agentless transfer

Console

gcloud

REST API

Agent-driven transfer

Console

gcloud

REST API

Cross-project Cloud Storage transfers

Organizational restrictions

Fine-grained permissions reference

Agentless transfer

Agent-driven transfer

Service agent permissions

Transfer agent account permissions

What's next

Configure access to a source: Cloud Storage