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
- Vendor Drop Box
- Authenticated Browser Download
- Central File for Shared Components
- Using a Group to Control Access to Objects
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:
||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.|
Granting the marketing analyst
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 opening the Permissions page. Add each user with Can edit permissions.
- Using gsutil, create a bucket named finance-marketing with the following
gsutil mb gs://finance-marketing
- Grant the marketing analyst (firstname.lastname@example.org) read access to the bucket by
running the command:
gsutil acl ch -u email@example.com: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:
||Granting the construction company project manager
Granting each vendor
||When a vendor uploads an object to their drop box they are automatically the owner of the object. As the owner, they are granted
||Granting the construction company project manager
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 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 firstname.lastname@example.org write access to the bucket with the following command:
gsutil acl ch -u email@example.com: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 firstname.lastname@example.org: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
READpermission 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
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.
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:
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.
- Obtain credentials and create a configuration file:
This will open a browser to complete the process.
- In the browser, sign in using the same vendor email, for example, email@example.com, that was granted write access to the bucket, and accept the request to manage your data.
- In the command shell where you
gsutil config, enter the authorization code you received in the browser and the project number of the project that contains the bucket. Note that you are working in the project with limited access, and you can not perform any project-level operations.
- 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
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
FULL_CONTROLpermission 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_CONTROLpermission 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
FULL_CONTROLpermission 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 firstname.lastname@example.org read access to the object:
gsutil acl ch -u email@example.com: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:
Using the bucket and file name from the example, you would send the following link to firstname.lastname@example.org:
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:
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.
Using a Group to Control Access to Objects
In this scenario, you want to make objects available to specific users, for example,
users invited to try out new software. In addition, you want to invite many users and do
not want to set
READ permission on each object for each user. Finally, if you
make the objects publicly readable and send links to access the objects (see
Accessing Google Developers Console) to
the invited customers, there is a risk the links may be sent to users who are not invited.
One way to handle this scenario is through the use of Google Groups. You can create a group and add only invited users to the group. Then, you can do one or both of the following:
- Add the group to the object ACL to allow users in the group to access the object. For more information, see Bucket and object ACLs.
- If appropriate for your scenario, add the group to the default object ACL for the bucket. Then, the ACL is applied to any new objects created in the bucket. For more information, see Default bucket and object ACLs.
When using groups to manage access to your resources, you should be aware of Group policies and limits that determine how many members can be in the group.
If you need to invite more users than can be added to a group, you should create a service that authenticates users and redirects them to a URL signed by a service account. For more information, see Signed URLs (query string authentication).