Sharing and Collaboration

This document shows you how to configure bucket and object ACLs for four data sharing and collaboration scenarios. To complete these scenarios, you must have the gsutil tool installed on your computer. For information about installing the gsutil tool, see gsutil Tool .

Storing and Maintaining Private Data

In this scenario, a company's marketing analyst wants to use Google Cloud Storage to back up confidential revenue forecasts and sales projection data. The data must be accessible only by the marketing analyst. The company's IT department oversees and manages the company's Google Cloud Storage account. Their primary management responsibilities include creating and sharing buckets so that various departments throughout the company have access to Google Cloud Storage.

To meet the confidentiality and privacy needs of the marketing analyst, the bucket and object permissions must ensure that the IT staff can maintain the bucket in which the spreadsheets are stored, but also ensure that the IT staff cannot READ (download) the data that is stored in the bucket. To accomplish this, you create a bucket named finance-marketing and grant the following permission:

Permission Description

FULL_CONTROL to the IT staff as project editors. Adding the IT staff as project editors enables them to perform common bucket management tasks, such as deleting objects and changing the ACLs on the bucket. It also allows the IT staff to list the contents of the finance-marketing bucket.

Permission	Description
`FULL_CONTROL` to the IT staff as project editors.	Adding the IT staff as project editors enables them to perform common bucket management tasks, such as deleting objects and changing the ACLs on the bucket. It also allows the IT staff to list the contents of the finance-marketing bucket.
`WRITE` (and implicit `READ` ) permission to the marketing analyst on the finance-marketing bucket.	Granting the marketing analyst `WRITE` permission on the finance-marketing bucket lets her upload data to the finance-marketing bucket and lets her list the objects that are in the finance-marketing bucket. Granting `WRITE` permission to the bucket implicitly grants `READ` permission for listing the objects in the bucket.


            WRITE

(and implicit


            READ

) permission to the marketing analyst on the finance-marketing bucket.

Granting the marketing analyst WRITE permission on the finance-marketing bucket lets her upload data to the finance-marketing bucket and lets her list the objects that are in the finance-marketing bucket.

Granting WRITE permission to the bucket implicitly grants READ permission for listing the objects in the bucket.

When the marketing analyst uploads objects to the finance-marketing bucket, she becomes the owner of the objects. As the owner, she is granted FULL_CONTROL permission on the objects, which lets her download and change permissions on the objects. Nobody except the marketing analyst can READ (download) the objects. Not even the IT staff who created the finance-marketing bucket can read the objects she uploads unless she grants them READ access. However, the IT staff can still list the contents of the finance-marketing bucket and they can delete and overwrite the files that are stored in the bucket.

Using gsutil to implement this scenario

Add the IT staff members as project editors in the Google Developers Console by selecting the project and opening the Permissions page. Add each user with Can edit permissions.
Using gsutil, create a bucket named finance-marketing with the following command:
```
gsutil mb gs://finance-marketing
```
Grant the marketing analyst ([email protected]) read access to the bucket by running the command:
```
gsutil acl ch -u [email protected]:R gs://finance-marketing
```

Note: As a best practice, you should avoid situations where an object can become inaccessible. In this scenario, if the marketing analyst leaves the company, nobody else can access the files that she uploaded to the finance-marketing bucket. To mitigate this risk, the marketing analyst could grant READ permission on the object to another analyst in the company. This allows another individual to download the objects. If you also grant the other analyst WRITE permission on the bucket, the other analyst can copy the objects to new files and become the owner of the new objects. This ensures that someone in the company will always own the object, and can update or change permissions as necessary.

Vendor Drop Box

In this scenario, a construction company works with several architectural design firms that deliver building plans for various projects. The construction company wants to set up a drop box for the vendor firms so they can upload architectural plans at various project milestones. The drop box must ensure the privacy of the construction company's clients, which means the drop box cannot allow the vendors to see each other's work. To accomplish this, you create a separate bucket for each architectural firm and grant the following permissions:

Permission	Description
`FULL_CONTROL` permission as a project editor to the construction company project manager.	Granting the construction company project manager `FULL_CONTROL` permission as a project editor enables him to list the contents of the all the buckets so he can see what the vendors have uploaded. It also allows him to delete objects at the end of each project milestone.
`WRITE` (and implicit `READ` ) permission to the vendors for their personal buckets.	Granting each vendor `WRITE` and `READ` permission on their personal buckets lets them upload new architectural plans to a bucket and list the architectural plans that are in their bucket. Granting `WRITE` permission to the bucket implicitly grants `READ` permission for listing the objects in the bucket.
`FULL_CONTROL` permission to vendors for the objects they upload to their buckets.	When a vendor uploads an object to their drop box they are automatically the owner of the object. As the owner, they are granted `FULL_CONTROL` permission on the object. This lets them download the objects and change the permissions on the objects.
`READ` permission to the construction company project manager for each object.	Granting the construction company project manager `READ` permission allows him to download the objects that the vendors are uploading.

Implementing this scenario

Project manager actions

The project manager should take the following actions to set up the bucket:

Add the company project manager as a project editor in the Google Developers Console by selecting the project and opening the Permissions page. Add the project manager with Can edit permissions.
Create a bucket named vendor1-building-plans with the following command:
```
gsutil mb gs://vendor1-building-plans
```
Grant [email protected] write access to the bucket with the following command:
```
gsutil acl ch -u [email protected]:W gs://vendor1-building-plans
```
To grant the permission to a group, use "-g" instead of "-u". For more information about setting ACLs using gsutil, see the acl command .
Set a default ACL on the vendor bucket so that objects created by the vendor are readable by the project manager:
```
gsutil defacl ch -u [email protected]:R gs://vendor1-building-plans
```
By default, object ACLs only give permissions to the object owner. In order for the project manager to download the object, either the vendor would need to explicitly give READ permission for each object they upload or the project manager can set a default ACL on the vendor bucket as shown above.

When you set up the ACLs this way, the project manager can download objects at the end of a project milestone and then delete the objects from the bucket so the bucket is empty for the next milestone submission. At the end of each project you can also remove the vendor's WRITE (and implicit READ ) permission from their bucket, which prevents them from uploading objects or listing bucket contents. However, any files that the vendor uploaded will always be owned by the vendor because you cannot change object ownership.

Vendor actions

To complete this scenario as a vendor, all you need to do is access the bucket. You will be required to sign in before uploading content, if you are not already. The easiest way for you to access the bucket is to use the Google Developers Console. You can also use the gsutil tool, but this requires setting up the tool.

Google Developers Console

Go to the following URL in a browser:
```
https://console.developers.google.com/storage/vendor1-building-plans/
```
Important: The trailing slash "/" at the end of the URI is required.

If you receive a "Forbidden" message when you try to access the bucket, ask the project manager to check that you were granted permission to the bucket as described in the Project manager actions above.
Click Upload to upload files.
You can upload multiple files or a folder using the Upload button. You can also drag and drop files to the browser window. For more information, see Uploading data to a bucket .

You are only able to upload to this bucket, no other buckets.

gustil

Obtain credentials and create a configuration file:
```
gsutil config
```
This will open a browser to complete the process.
In the browser, sign in using the same vendor email, for example, [email protected], that was granted write access to the bucket, and accept the request to manage your data.
In the command shell you started gsutil config , enter the authorization code you received in the browser and the project ID of the project that contains the bucket.
Use gsutil to list your vendor bucket:
```
gsutil ls gs://vendor1-building-plans
```
You are only able to see what is in this bucket, no other buckets.
Upload data to the vendor bucket:
```
gsutil cp plans.zip gs://vendor1-building-plans
```
You are only able to upload to this bucket, no other buckets.

Authenticated Browser Downloads

In this scenario, a client wants to make files available to specific individuals through simple browser downloads. You can do this by using the Google Cloud Storage cookie-based authentication feature. To use the feature, you grant a user READ permission to an object and then you give the user a special URL to the object. When the user clicks the URL, Google Cloud Storage prompts them to sign in to their Google account (if they are not already logged in) and the object is downloaded to their computer. Only users who have READ or FULL_CONTROL permission on the object are allowed to download it. All other users get a 403 Forbidden (access denied) error.

You can implement cookie-based authentication in four easy steps:

Create a bucket for sharing your objects.
If you already have a bucket that you want to use, that's fine, but keep in mind you're serving secure content from the bucket. As a best practice, make sure anonymous users don't have READ / WRITE or FULL_CONTROL permission on the bucket.
Upload the object you want to share.
When you upload an object you become the owner of the object, which means you are granted FULL_CONTROL permission and you can modify the object's ACLs.
Modify ACLs on the object you uploaded.
To allow a user to download an object, you must grant the user READ or FULL_CONTROL permission on the object.
Provide users with a special URL to the object.
The URL consists of a secure sockets layer (SSL) URI that is scoped to the bucket and the object. It doesn't matter how you make this URL available to users. You can send it to them or you can post it on a web page.

Use gsutil to implement this scenario

Create a new bucket named example-maps with the following command:
```
gsutil mb gs://example-maps
```
Upload the object you want to share:
```
gsutil cp london.jpg gs://example-maps
```

Grant [email protected] read access to the object:

gsutil acl ch -u [email protected]:R gs://example-maps/london.jpg

Send your object's URL to your users.
To use the authenticated browser download feature, construct a URL to your object using the following syntax:
https://storage.cloud.google.com/ <bucket> / <object>

Using the bucket and file name from the example, you would send the following link to [email protected]:

https://storage.cloud.google.com/example-maps/london.jpg

Central File for Shared Components

In this scenario, a small company wants to use Google Cloud Storage as a storage system for their employees. The IT administrator creates a project in the Google Developers Console and creates buckets for each employee. To make it easier for employees to use Google Cloud Storage, the administrator wants to create and store company-wide configurations, such as the project ID and API version to use, in a central file that employees can point to in their BOTO configuration path. This eliminates the need for each employee to set the shared parts of the configuration manually and allows the administrator to easily change these shared configurations if necessary.

To accomplish this, create a central boto configuration file that can be used by gsutil through the following steps:

Create a central boto configuration file that is readable by all employees.
The boto configuration file might contain the following information:
```
[gsutil]
default_project_id = 123456789123
default_api_version = 2
```
Instruct employees to install gsutil.
During gsutil installation, employees still need to generate individual authentication credentials because you cannot share authentication credentials centrally. However, employees can leave the project ID field blank because it is provided by the central configuration file.
Instruct employees to add a BOTO_PATH environment variable.
The BOTO_PATH environment variable lists the path of the centrally located configuration file, followed by the employee's local configuration file like so:
```
BOTO_PATH =/<dir>/boto.cfg:home/<user>/.boto
```

When employees run gsutil, they will automatically have a project ID and API version set for them. If necessary, the administrator can change the project ID, API version, and other settings in the central configuration file and have the changes reflected for all employees using the central configuration file.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Google Cloud Storage