feat: Add custom scopes for access tokens from the metadata service (#…

…633)

This works for App Engine, Cloud Run and Flex. On Compute Engine you
can request custom scopes, but they are ignored.

Co-authored-by: Tres Seaver <tseaver@palladion.com>
Co-authored-by: Bu Sun Kim <8822365+busunkim96@users.noreply.github.com>

google/auth/_default.py

@@ -274,10 +274,11 @@ def default(scopes=None, request=None, quota_project_id=None):
             gcloud config set project
 
     3. If the application is running in the `App Engine standard environment`_
-       then the credentials and project ID from the `App Identity Service`_
-       are used.
-    4. If the application is running in `Compute Engine`_ or the
-       `App Engine flexible environment`_ then the credentials and project ID
+       (first generation) then the credentials and project ID from the
+       `App Identity Service`_ are used.
+    4. If the application is running in `Compute Engine`_ or `Cloud Run`_ or
+       the `App Engine flexible environment`_ or the `App Engine standard
+       environment`_ (second generation) then the credentials and project ID
        are obtained from the `Metadata Service`_.
     5. If no credentials are found,
        :class:`~google.auth.exceptions.DefaultCredentialsError` will be raised.
@@ -293,6 +294,7 @@ def default(scopes=None, request=None, quota_project_id=None):
             /appengine/flexible
     .. _Metadata Service: https://cloud.google.com/compute/docs\
             /storing-retrieving-metadata
+    .. _Cloud Run: https://cloud.google.com/run
 
     Example::
 

google/auth/_default_async.py

@@ -187,10 +187,11 @@ def default_async(scopes=None, request=None, quota_project_id=None):
             gcloud config set project
 
     3. If the application is running in the `App Engine standard environment`_
-       then the credentials and project ID from the `App Identity Service`_
-       are used.
-    4. If the application is running in `Compute Engine`_ or the
-       `App Engine flexible environment`_ then the credentials and project ID
+       (first generation) then the credentials and project ID from the
+       `App Identity Service`_ are used.
+    4. If the application is running in `Compute Engine`_ or `Cloud Run`_ or
+       the `App Engine flexible environment`_ or the `App Engine standard
+       environment`_ (second generation) then the credentials and project ID
        are obtained from the `Metadata Service`_.
     5. If no credentials are found,
        :class:`~google.auth.exceptions.DefaultCredentialsError` will be raised.
@@ -206,6 +207,7 @@ def default_async(scopes=None, request=None, quota_project_id=None):
             /appengine/flexible
     .. _Metadata Service: https://cloud.google.com/compute/docs\
             /storing-retrieving-metadata
+    .. _Cloud Run: https://cloud.google.com/run
 
     Example::
 

google/auth/compute_engine/_metadata.py

@@ -234,7 +234,7 @@ def get_service_account_info(request, service_account="default"):
     return get(request, path, params={"recursive": "true"})
 
 
-def get_service_account_token(request, service_account="default"):
+def get_service_account_token(request, service_account="default", scopes=None):
     """Get the OAuth 2.0 access token for a service account.
 
     Args:
@@ -243,17 +243,24 @@ def get_service_account_token(request, service_account="default"):
         service_account (str): The string 'default' or a service account email
             address. The determines which service account for which to acquire
             an access token.
-
+        scopes (Optional[Union[str, List[str]]]): Optional string or list of
+            strings with auth scopes.
     Returns:
         Union[str, datetime]: The access token and its expiration.
 
     Raises:
         google.auth.exceptions.TransportError: if an error occurred while
             retrieving metadata.
     """
-    token_json = get(
-        request, "instance/service-accounts/{0}/token".format(service_account)
-    )
+    if scopes:
+        if not isinstance(scopes, str):
+            scopes = ",".join(scopes)
+        params = {"scopes": scopes}
+    else:
+        params = None
+
+    path = "instance/service-accounts/{0}/token".format(service_account)
+    token_json = get(request, path, params=params)
     token_expiry = _helpers.utcnow() + datetime.timedelta(
         seconds=token_json["expires_in"]
     )

google/auth/compute_engine/credentials.py

@@ -32,29 +32,28 @@
 from google.oauth2 import _client
 
 
-class Credentials(credentials.ReadOnlyScoped, credentials.CredentialsWithQuotaProject):
+class Credentials(credentials.Scoped, credentials.CredentialsWithQuotaProject):
     """Compute Engine Credentials.
 
     These credentials use the Google Compute Engine metadata server to obtain
-    OAuth 2.0 access tokens associated with the instance's service account.
+    OAuth 2.0 access tokens associated with the instance's service account,
+    and are also used for Cloud Run, Flex and App Engine (except for the Python
+    2.7 runtime).
 
     For more information about Compute Engine authentication, including how
     to configure scopes, see the `Compute Engine authentication
     documentation`_.
 
-    .. note:: Compute Engine instances can be created with scopes and therefore
-        these credentials are considered to be 'scoped'. However, you can
-        not use :meth:`~google.auth.credentials.ScopedCredentials.with_scopes`
-        because it is not possible to change the scopes that the instance
-        has. Also note that
-        :meth:`~google.auth.credentials.ScopedCredentials.has_scopes` will not
-        work until the credentials have been refreshed.
+    .. note:: On Compute Engine the metadata server ignores requested scopes.
+        On Cloud Run, Flex and App Engine the server honours requested scopes.
 
     .. _Compute Engine authentication documentation:
         https://cloud.google.com/compute/docs/authentication#using
     """
 
-    def __init__(self, service_account_email="default", quota_project_id=None):
+    def __init__(
+        self, service_account_email="default", quota_project_id=None, scopes=None
+    ):
         """
         Args:
             service_account_email (str): The service account email to use, or
@@ -66,6 +65,7 @@ def __init__(self, service_account_email="default", quota_project_id=None):
         super(Credentials, self).__init__()
         self._service_account_email = service_account_email
         self._quota_project_id = quota_project_id
+        self._scopes = scopes
 
     def _retrieve_info(self, request):
         """Retrieve information about the service account.
@@ -81,7 +81,10 @@ def _retrieve_info(self, request):
         )
 
         self._service_account_email = info["email"]
-        self._scopes = info["scopes"]
+
+        # Don't override scopes requested by the user.
+        if self._scopes is None:
+            self._scopes = info["scopes"]
 
     def refresh(self, request):
         """Refresh the access token and scopes.
@@ -98,7 +101,9 @@ def refresh(self, request):
         try:
             self._retrieve_info(request)
             self.token, self.expiry = _metadata.get_service_account_token(
-                request, service_account=self._service_account_email
+                request,
+                service_account=self._service_account_email,
+                scopes=self._scopes,
             )
         except exceptions.TransportError as caught_exc:
             new_exc = exceptions.RefreshError(caught_exc)
@@ -115,14 +120,25 @@ def service_account_email(self):
 
     @property
     def requires_scopes(self):
-        """False: Compute Engine credentials can not be scoped."""
-        return False
+        return not self._scopes
 
     @_helpers.copy_docstring(credentials.CredentialsWithQuotaProject)
     def with_quota_project(self, quota_project_id):
         return self.__class__(
             service_account_email=self._service_account_email,
             quota_project_id=quota_project_id,
+            scopes=self._scopes,
+        )
+
+    @_helpers.copy_docstring(credentials.Scoped)
+    def with_scopes(self, scopes):
+        # Compute Engine credentials can not be scoped (the metadata service
+        # ignores the scopes parameter). App Engine, Cloud Run and Flex support
+        # requesting scopes.
+        return self.__class__(
+            scopes=scopes,
+            service_account_email=self._service_account_email,
+            quota_project_id=self._quota_project_id,
         )
 
 

system_tests/noxfile.py

@@ -315,7 +315,7 @@ def default_explicit_service_account_async(session):
     session.env[EXPECT_PROJECT_ENV] = "1"
     session.install(*(TEST_DEPENDENCIES_SYNC + TEST_DEPENDENCIES_ASYNC))
     session.install(LIBRARY_DIR)
-    session.run("pytest", "system_tests_async/test_default.py", 
+    session.run("pytest", "system_tests_async/test_default.py",
     "system_tests_async/test_id_token.py")
 
 

tests/compute_engine/test_credentials.py

@@ -55,8 +55,8 @@ def test_default_state(self):
         assert not self.credentials.valid
         # Expiration hasn't been set yet
         assert not self.credentials.expired
-        # Scopes aren't needed
-        assert not self.credentials.requires_scopes
+        # Scopes are needed
+        assert self.credentials.requires_scopes
         # Service account email hasn't been populated
         assert self.credentials.service_account_email == "default"
         # No quota project
@@ -96,6 +96,45 @@ def test_refresh_success(self, get, utcnow):
         # expired)
         assert self.credentials.valid
 
+    @mock.patch(
+        "google.auth._helpers.utcnow",
+        return_value=datetime.datetime.min + _helpers.CLOCK_SKEW,
+    )
+    @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
+    def test_refresh_success_with_scopes(self, get, utcnow):
+        get.side_effect = [
+            {
+                # First request is for sevice account info.
+                "email": "service-account@example.com",
+                "scopes": ["one", "two"],
+            },
+            {
+                # Second request is for the token.
+                "access_token": "token",
+                "expires_in": 500,
+            },
+        ]
+
+        # Refresh credentials
+        scopes = ["three", "four"]
+        self.credentials = self.credentials.with_scopes(scopes)
+        self.credentials.refresh(None)
+
+        # Check that the credentials have the token and proper expiration
+        assert self.credentials.token == "token"
+        assert self.credentials.expiry == (utcnow() + datetime.timedelta(seconds=500))
+
+        # Check the credential info
+        assert self.credentials.service_account_email == "service-account@example.com"
+        assert self.credentials._scopes == scopes
+
+        # Check that the credentials are valid (have a token and are not
+        # expired)
+        assert self.credentials.valid
+
+        kwargs = get.call_args[1]
+        assert kwargs == {"params": {"scopes": "three,four"}}
+
     @mock.patch("google.auth.compute_engine._metadata.get", autospec=True)
     def test_refresh_error(self, get):
         get.side_effect = exceptions.TransportError("http error")
@@ -138,6 +177,14 @@ def test_with_quota_project(self):
 
         assert quota_project_creds._quota_project_id == "project-foo"
 
+    def test_with_scopes(self):
+        assert self.credentials._scopes is None
+
+        scopes = ["one", "two"]
+        self.credentials = self.credentials.with_scopes(scopes)
+
+        assert self.credentials._scopes == scopes
+
 
 class TestIDTokenCredentials(object):
     credentials = None