Repository: GoogleCloudPlatform/google-auth-library-python
Pull request #108 (2017-02-15 20:47:26)

Add IAM signer
/cc @matthewg


jonparrott: FYI to @elibixby as well.
jonparrott: Nope, just 200.

On Wed, Feb 15, 2017, 4:03 PM Luke Sneeringer <notifications@github.com>
wrote:

> *@lukesneeringer* commented on this pull request.
> ------------------------------
>
> In google/auth/iam.py
> <https://github.com/GoogleCloudPlatform/google-auth-library-python/pull/108#discussion_r101415211>
> :
>
> > +    def _make_signing_request(self, message):
> +        """Makes a request to the API signBlob API."""
> +        message = _helpers.to_bytes(message)
> +
> +        method = 'POST'
> +        url = _SIGN_BLOB_URI.format(self._service_account_email)
> +        headers = {}
> +        body = json.dumps({
> +            'bytesToSign': base64.b64encode(message).decode('utf-8'),
> +        })
> +
> +        self._credentials.before_request(self._request, method, url, headers)
> +        response = self._request(
> +            url=url, method=method, body=body, headers=headers)
> +
> +        if response.status != http_client.OK:
>
> Are there ever cases where this particular API would send back successes
> that are not 200? (Say, 201 or 202?)
>
> —
> You are receiving this because you authored the thread.
> Reply to this email directly, view it on GitHub
> <https://github.com/GoogleCloudPlatform/google-auth-library-python/pull/108#pullrequestreview-22143321>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/AAPUc-3fMDD2cZ4053w7zE7onq-BugWvks5rc5JHgaJpZM4MCOf8>
> .
>

lukesneeringer: Is there any risk of that changing? Cards on table: I usually do `status < 400` for this kind of check, since it seems more future-proof.

If you are pretty sure that everything returned from the IAM API will always be 200 for a success case, though, then this is good to go.
jonparrott: > If you are pretty sure that everything returned from the IAM API will always be 200 for a success case, though, then this is good to go.

I feel like any change in that behavior should necessitate a change in our code. I also don't think they'll mess with it.

Patch:
diff --git a/docs/reference/google.auth.iam.rst b/docs/reference/google.auth.iam.rst
new file mode 100644
index 0000000..8a5edb4
--- /dev/null
+++ b/docs/reference/google.auth.iam.rst
@@ -0,0 +1,7 @@
+google.auth.iam module
+======================
+
+.. automodule:: google.auth.iam
+    :members:
+    :inherited-members:
+    :show-inheritance:
diff --git a/docs/reference/google.auth.rst b/docs/reference/google.auth.rst
index 2d50672..244d0bb 100644
--- a/docs/reference/google.auth.rst
+++ b/docs/reference/google.auth.rst
@@ -24,5 +24,6 @@ Submodules
    google.auth.crypt
    google.auth.environment_vars
    google.auth.exceptions
+   google.auth.iam
    google.auth.jwt
 
diff --git a/google/auth/crypt.py b/google/auth/crypt.py
index 1305cc8..05839b4 100644
--- a/google/auth/crypt.py
+++ b/google/auth/crypt.py
@@ -182,6 +182,7 @@ class Signer(object):
     def __init__(self, private_key, key_id=None):
         self._key = private_key
         self.key_id = key_id
+        """Optional[str]: The key ID used to identify this private key."""
 
     def sign(self, message):
         """Signs a message.
diff --git a/google/auth/iam.py b/google/auth/iam.py
new file mode 100644
index 0000000..efa3127
--- /dev/null
+++ b/google/auth/iam.py
@@ -0,0 +1,117 @@
+# Copyright 2017 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tools for using the Google `Cloud Identity and Access Management (IAM)
+API`_'s auth-related functionality.
+
+.. _Cloud Identity and Access Management (IAM) API:
+    https://cloud.google.com/iam/docs/
+"""
+
+import base64
+import json
+
+from six.moves import http_client
+
+from google.auth import _helpers
+from google.auth import exceptions
+
+_IAM_API_ROOT_URI = 'https://iam.googleapis.com/v1'
+_SIGN_BLOB_URI = (
+    _IAM_API_ROOT_URI + '/projects/-/serviceAccounts/{}:signBlob?alt=json')
+
+
+class Signer(object):
+    """Signs messages using the IAM `signBlob API`_.
+
+    This is useful when you need to sign bytes but do not have access to the
+    credential's private key file.
+
+    .. warning::
+        The IAM API signs bytes using Google-managed keys. Because of this
+        it's possible that the key used to sign bytes will change. In some
+        cases this change can occur between successive calls to :attr:`key_id`
+        and :meth:`sign`. This could result in a signature that was signed
+        with a different key than the one indicated by :attr:`key_id`. It's
+        recommended that if you use this in your code that you account for
+        this behavior by building in retry logic.
+
+    .. _signBlob API:
+        https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts
+        /signBlob
+    """
+
+    def __init__(self, request, credentials, service_account_email):
+        """
+        Args:
+            request (google.auth.transport.Request): The object used to make
+                HTTP requests.
+            credentials (google.auth.credentials.Credentials): The credentials
+                that will be used to authenticate the request to the IAM API.
+                The credentials must have of one the following scopes:
+
+                - https://www.googleapis.com/auth/iam
+                - https://www.googleapis.com/auth/cloud-platform
+            service_account_email (str): The service account email identifying
+                which service account to use to sign bytes. Often, this can
+                be the same as the service account email in the given
+                credentials.
+        """
+        self._request = request
+        self._credentials = credentials
+        self._service_account_email = service_account_email
+
+    def _make_signing_request(self, message):
+        """Makes a request to the API signBlob API."""
+        message = _helpers.to_bytes(message)
+
+        method = 'POST'
+        url = _SIGN_BLOB_URI.format(self._service_account_email)
+        headers = {}
+        body = json.dumps({
+            'bytesToSign': base64.b64encode(message).decode('utf-8'),
+        })
+
+        self._credentials.before_request(self._request, method, url, headers)
+        response = self._request(
+            url=url, method=method, body=body, headers=headers)
+
+        if response.status != http_client.OK:
+            raise exceptions.TransportError(
+                'Error calling the IAM signBytes API: {}'.format(
+                    response.data))
+
+        return json.loads(response.data.decode('utf-8'))
+
+    @property
+    def key_id(self):
+        """Optional[str]: The key ID used to identify this private key.
+
+        .. note::
+            This makes an API request to the IAM API.
+        """
+        response = self._make_signing_request('')
+        return response['keyId']
+
+    def sign(self, message):
+        """Signs a message.
+
+        Args:
+            message (Union[str, bytes]): The message to be signed.
+
+        Returns:
+            bytes: The signature of the message.
+        """
+        response = self._make_signing_request(message)
+        return base64.b64decode(response['signature'])


Test patch:
diff --git a/tests/test_iam.py b/tests/test_iam.py
new file mode 100644
index 0000000..5ac9911
--- /dev/null
+++ b/tests/test_iam.py
@@ -0,0 +1,100 @@
+# Copyright 2017 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import base64
+import datetime
+import json
+
+import mock
+import pytest
+from six.moves import http_client
+
+from google.auth import exceptions
+from google.auth import iam
+from google.auth import transport
+import google.auth.credentials
+
+
+def make_request(status, data=None):
+    response = mock.Mock(spec=transport.Response)
+    response.status = status
+
+    if data is not None:
+        response.data = json.dumps(data).encode('utf-8')
+
+    return mock.Mock(return_value=response, spec=transport.Request)
+
+
+def make_credentials():
+    class CredentialsImpl(google.auth.credentials.Credentials):
+        def __init__(self):
+            super(CredentialsImpl, self).__init__()
+            self.token = 'token'
+            # Force refresh
+            self.expiry = datetime.datetime.min
+
+        def refresh(self, request):
+            pass
+
+    return CredentialsImpl()
+
+
+class TestSigner(object):
+    def test_constructor(self):
+        request = mock.sentinel.request
+        credentials = mock.Mock(spec=google.auth.credentials.Credentials)
+
+        signer = iam.Signer(
+            request, credentials, mock.sentinel.service_account_email)
+
+        assert signer._request == mock.sentinel.request
+        assert signer._credentials == credentials
+        assert (signer._service_account_email ==
+                mock.sentinel.service_account_email)
+
+    def test_key_id(self):
+        key_id = '123'
+        request = make_request(http_client.OK, data={'keyId': key_id})
+        credentials = make_credentials()
+
+        signer = iam.Signer(
+            request, credentials, mock.sentinel.service_account_email)
+
+        assert signer.key_id == '123'
+        auth_header = request.call_args[1]['headers']['authorization']
+        assert auth_header == 'Bearer token'
+
+    def test_sign_bytes(self):
+        signature = b'DEADBEEF'
+        encoded_signature = base64.b64encode(signature).decode('utf-8')
+        request = make_request(
+            http_client.OK, data={'signature': encoded_signature})
+        credentials = make_credentials()
+
+        signer = iam.Signer(
+            request, credentials, mock.sentinel.service_account_email)
+
+        returned_signature = signer.sign('123')
+
+        assert returned_signature == signature
+
+    def test_sign_bytes_failure(self):
+        request = make_request(http_client.UNAUTHORIZED)
+        credentials = make_credentials()
+
+        signer = iam.Signer(
+            request, credentials, mock.sentinel.service_account_email)
+
+        with pytest.raises(exceptions.TransportError):
+            signer.sign('123')