diff --git a/docs/reference/google.auth.iam.rst b/docs/reference/google.auth.iam.rst new file mode 100644 index 000000000..8a5edb450 --- /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 2d5067241..244d0bbd3 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 1305cc843..05839b46f 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 000000000..efa312710 --- /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']) diff --git a/tests/test_iam.py b/tests/test_iam.py new file mode 100644 index 000000000..5ac991168 --- /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')