From 3b2106ed30303350d3a73f37d0295f68f42a44b5 Mon Sep 17 00:00:00 2001
From: Michael Pratt <michael@pratt.im>
Date: Sun, 24 Sep 2017 11:25:57 -0700
Subject: [PATCH] gs: document required permissions

In the manual, state which standard roles the service account must
have to work correctly, as well as the specific permissions required,
for creating even more specific custom roles.
---
 doc/manual.rst            | 22 ++++++++++++++++++----
 internal/backend/gs/gs.go | 13 ++++++++++++-
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/doc/manual.rst b/doc/manual.rst
index 3e205e6c1..6841deb21 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -405,11 +405,22 @@ established.
 Google Cloud Storage
 ~~~~~~~~~~~~~~~~~~~~
 
-Restic supports Google Cloud Storage as a backend. In order for this to work
-you first need create a "service account" and download the JSON key file for
-it. In addition, you need the Google Project ID that you can see in the Google
+Restic supports Google Cloud Storage as a backend.
+
+Restic connects to Google Cloud Storage via a `service account`_.
+
+For normal restic operation, the service account must have the
+``storage.objects.{create,delete,get,list}`` permissions for the bucket. These
+are included in the "Storage Object Admin" role. For ``restic init``, the
+service account must also have the ``storage.buckets.get`` and
+``storage.buckets.create`` (if the bucket does not exist) permissions. These
+are included in the "Storage Admin" role.
+
+`Create a service account key`_ and download the JSON credentials file.
+
+In addition, you need the Google Project ID that you can see in the Google
 Cloud Platform console at the "Storage/Settings" menu. Export the path to the
-JSON credentials file and the project ID as follows:
+JSON key file and the project ID as follows:
 
 .. code-block:: console
 
@@ -432,6 +443,9 @@ The number of concurrent connections to the GCS service can be set with the
 `-o gs.connections=10`. By default, at most five parallel connections are
 established.
 
+.. _service account: https://cloud.google.com/storage/docs/authentication#service_accounts
+.. _Create a service account key: https://cloud.google.com/storage/docs/authentication#generating-a-private-key
+
 
 Password prompt on Windows
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/internal/backend/gs/gs.go b/internal/backend/gs/gs.go
index c70e82e9d..ea003d955 100644
--- a/internal/backend/gs/gs.go
+++ b/internal/backend/gs/gs.go
@@ -21,7 +21,13 @@ import (
 	storage "google.golang.org/api/storage/v1"
 )
 
-// Backend stores data on an gs endpoint.
+// Backend stores data in a GCS bucket.
+//
+// The service account used to access the bucket must have these permissions:
+//  * storage.objects.create
+//  * storage.objects.delete
+//  * storage.objects.get
+//  * storage.objects.list
 type Backend struct {
 	service      *storage.Service
 	projectID    string
@@ -95,6 +101,11 @@ func Open(cfg Config) (restic.Backend, error) {
 
 // Create opens the gs backend at the specified bucket and creates the bucket
 // if it does not exist yet.
+//
+// In addition to the permissions required by Backend, Create requires these
+// permissions:
+//  * storage.buckets.get
+//  * storage.buckets.create (if the bucket doesn't exist)
 func Create(cfg Config) (restic.Backend, error) {
 	be, err := open(cfg)
 	if err != nil {