Repository: googleapis/google-cloud-python

Issue:
Blob IAM support apparently invalid
While writing system tests for the `requester_pays` feature, I triggered the following:

```python
Traceback (most recent call last):
  File "/home/tseaver/projects/agendaless/Google/src/google-cloud-python/storage/tests/system.py", line 372, in test_blob_acl_iam_w_user_project
    blob.set_iam_policy(policy)
  File "/home/tseaver/projects/agendaless/Google/src/google-cloud-python/storage/google/cloud/storage/blob.py", line 1148, in set_iam_policy
    _target_object=None)
  File "/home/tseaver/projects/agendaless/Google/src/google-cloud-python/storage/.nox/sys-3-6/lib/python3.6/site-packages/google/cloud/_http.py", line 293, in api_request
    raise exceptions.from_http_response(response)
google.api.core.exceptions.BadRequest: 400 PUT https://www.googleapis.com/storage/v1/b/new_1506705016579/o/SmallFile/iam?userProject=citric-celerity-697: roles/storage.objectViewer is not a valid role for projects/_/buckets/new_1506705016579/objects/SmallFile#0.
```

Note that the earlier call to `Blob.get_iam_policy` does succeed, returning:

```python
(Pdb) pp policy.to_api_repr()
{'bindings': [{'members': ['projectEditor:some-project-742',
                           'projectOwner:some-project-742',
                           'serviceAccount:1065521786570-19reuv03qbdp37du41inh9gtd1s35g1j@developer.gserviceaccount.com'],
               'role': 'roles/storage.legacyObjectOwner'},
              {'members': ['projectViewer:some-project-742'],
               'role': 'roles/storage.legacyObjectReader'},
              {'members': ['allUsers'], 'role': 'roles/storage.objectViewer'}],
 'etag': 'CAM='}
```


We don't have existing system tests for `Blob.set_iam_policy`, but the [Storage IAM docs](https://cloud.google.com/storage/docs/access-control/using-iam-permissions) don't define any IAM operations for blobs, only for buckets and projects.  Indeed, they say:

> To learn about controlling access to individual objects in your buckets, see [Access Control Lists](https://cloud.google.com/storage/docs/access-control/lists).

The [API documentation for Objects](https://cloud.google.com/storage/docs/json_api/v1/objects) also doesn't (any longer?) show `getIamPolicy`, `setIamPolicy`, or `testIamPermissions`.

@lukesneeringer can you loop somebody in to clarify?



Discussion:
@frankyn confirmed to me offline:

>  There is no Object level IAM only Object Level ACL. 
It turns out that `Blob.set_iam_policy` can only assign the following "legacy" roles:

- `roles/storage.legacyObjectReader`
- `roles/storage.legacyObjectOwner`
IAM object-level methods should not be deprecated. We should document how to use these methods to assign legacy roles instead.
@frankyn ISTM that the back-end docs need to be updated correspondingly (and first, so that we track them without guesswork).
Good point. I'm working on resolving this in Storage docs. I'll update this issue.
@frankyn ping?
I'm out of office until Monday! I'll pick back up then. Apologies for the
delay.

On Jan 4, 2018 11:37 AM, "Tres Seaver" <notifications@github.com> wrote:

> @frankyn <https://github.com/frankyn> ping?
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/GoogleCloudPlatform/google-cloud-python/issues/4087#issuecomment-355362540>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/AB0bwLK3FIgA9YM7FBKKDqZqVkh518DDks5tHRpVgaJpZM4PpDhF>
> .
>

@tseaver docs were blocked by an internal bug and I will check-in again this week. Apologies for the delay. 
@frankyn I still don't see API documentation for `objects.getIamPermissions` et. al.
Will update soon. I need to sync with a few stakeholders on the GCS team before continuing there exist additional open questions before introducing the docs back into the world. Setting up meeting for mid-next week given some are OOO. I will have a better update then. Thank you for patience.
Sent a document for GCS team review to determine consensus for what to do here. 
@frankyn ping?
Hey @tseaver, responding through hangouts.

Resolving patch:
diff --git a/storage/google/cloud/storage/blob.py b/storage/google/cloud/storage/blob.py
--- a/storage/google/cloud/storage/blob.py
+++ b/storage/google/cloud/storage/blob.py
@@ -1183,8 +1183,13 @@ def create_resumable_upload_session(
     def get_iam_policy(self, client=None):
         """Retrieve the IAM policy for the object.
 
-        See
-        https://cloud.google.com/storage/docs/json_api/v1/objects/getIamPolicy
+        .. note:
+
+           Blob- / object-level IAM support does not yet exist and methods
+           currently call an internal ACL backend not providing any utility
+           beyond the blob's :attr:`acl` at this time. The API may be enhanced
+           in the future and is currently undocumented. Use :attr:`acl` for
+           managing object access control.
 
         If :attr:`user_project` is set on the bucket, bills the API request
         to that project.
@@ -1215,8 +1220,13 @@ def get_iam_policy(self, client=None):
     def set_iam_policy(self, policy, client=None):
         """Update the IAM policy for the bucket.
 
-        See
-        https://cloud.google.com/storage/docs/json_api/v1/objects/setIamPolicy
+        .. note:
+
+           Blob- / object-level IAM support does not yet exist and methods
+           currently call an internal ACL backend not providing any utility
+           beyond the blob's :attr:`acl` at this time. The API may be enhanced
+           in the future and is currently undocumented. Use :attr:`acl` for
+           managing object access control.
 
         If :attr:`user_project` is set on the bucket, bills the API request
         to that project.
@@ -1253,8 +1263,13 @@ def set_iam_policy(self, policy, client=None):
     def test_iam_permissions(self, permissions, client=None):
         """API call:  test permissions
 
-        See
-        https://cloud.google.com/storage/docs/json_api/v1/objects/testIamPermissions
+        .. note:
+
+           Blob- / object-level IAM support does not yet exist and methods
+           currently call an internal ACL backend not providing any utility
+           beyond the blob's :attr:`acl` at this time. The API may be enhanced
+           in the future and is currently undocumented. Use :attr:`acl` for
+           managing object access control.
 
         If :attr:`user_project` is set on the bucket, bills the API request
         to that project.


Test patch: