fix: improve user guide for Impersonation and SA

docs/user-guide.rst

@@ -62,57 +62,6 @@ store service account private keys locally.
 .. _Google Cloud SDK: https://cloud.google.com/sdk
 
 
-Service account private key files
-+++++++++++++++++++++++++++++++++
-
-A service account private key file can be used to obtain credentials for a
-service account. You can create a private key using the `Credentials page of the
-Google Cloud Console`_. Once you have a private key you can either obtain
-credentials one of three ways:
-
-1. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full
-   path to your service account private key file
-
-   .. code-block:: bash
-
-        $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
-
-   Then, use :ref:`application default credentials <application-default>`.
-   :func:`default` checks for the ``GOOGLE_APPLICATION_CREDENTIALS``
-   environment variable before all other checks, so this will always use the
-   credentials you explicitly specify.
-
-2. Use :meth:`service_account.Credentials.from_service_account_file
-   <google.oauth2.service_account.Credentials.from_service_account_file>`::
-
-        from google.oauth2 import service_account
-
-        credentials = service_account.Credentials.from_service_account_file(
-            '/path/to/key.json')
-
-        scoped_credentials = credentials.with_scopes(
-            ['https://www.googleapis.com/auth/cloud-platform'])
-
-3. Use :meth:`service_account.Credentials.from_service_account_info
-   <google.oauth2.service_account.Credentials.from_service_account_info>`::
-
-        import json
-
-        from google.oauth2 import service_account
-
-        json_acct_info = json.loads(function_to_get_json_creds())
-        credentials = service_account.Credentials.from_service_account_info(
-            json_acct_info)
-
-        scoped_credentials = credentials.with_scopes(
-            ['https://www.googleapis.com/auth/cloud-platform'])
-
-.. warning:: Private keys must be kept secret. If you expose your private key it
-    is recommended to revoke it immediately from the Google Cloud Console.
-
-.. _Credentials page of the Google Cloud Console:
-    https://console.cloud.google.com/apis/credentials
-
 Compute Engine, Container Engine, and the App Engine flexible environment
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -231,6 +180,7 @@ You can also use :class:`google_auth_oauthlib.flow.Flow` to perform the OAuth
 .. _requests-oauthlib:
     https://requests-oauthlib.readthedocs.io/en/latest/
 
+
 External credentials (Workload identity federation)
 +++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -981,7 +931,8 @@ Impersonated credentials
 ++++++++++++++++++++++++
 
 Impersonated Credentials allows one set of credentials issued to a user or service account
-to impersonate another. The source credentials must be granted
+to impersonate a service account. Impersonation is the preferred way of using service account for
+local development over downloading the service account key. The source credentials must be granted
 the "Service Account Token Creator" IAM role. ::
 
     from google.auth import impersonated_credentials
@@ -1006,6 +957,63 @@ In the example above `source_credentials` does not have direct access to list bu
 in the target project. Using `ImpersonatedCredentials` will allow the source_credentials
 to assume the identity of a target_principal that does have access.
 
+It is possible to provide a delegation chain through `delegates` paramter while
+initializing the impersonated credential. Refer `create short lived credentials delegated`_ for more details on delegation chain.
+
+.. _create short lived credentials delegated: https://cloud.google.com/iam/docs/create-short-lived-credentials-delegated
+
+
+Service account private key files
++++++++++++++++++++++++++++++++++
+
+A service account private key file can be used to obtain credentials for a service account. If you are not
+able to use any of the authentication methods listed above, you can create a private key using `Credentials page of the
+Google Cloud Console`_. Once you have a private key you can obtain
+credentials one of three ways:
+
+1. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full
+   path to your service account private key file
+
+   .. code-block:: bash
+
+        $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
+
+   Then, use :ref:`application default credentials <application-default>`.
+   :func:`default` checks for the ``GOOGLE_APPLICATION_CREDENTIALS``
+   environment variable before all other checks, so this will always use the
+   credentials you explicitly specify.
+
+2. Use :meth:`service_account.Credentials.from_service_account_file
+   <google.oauth2.service_account.Credentials.from_service_account_file>`::
+
+        from google.oauth2 import service_account
+
+        credentials = service_account.Credentials.from_service_account_file(
+            '/path/to/key.json')
+
+        scoped_credentials = credentials.with_scopes(
+            ['https://www.googleapis.com/auth/cloud-platform'])
+
+3. Use :meth:`service_account.Credentials.from_service_account_info
+   <google.oauth2.service_account.Credentials.from_service_account_info>`::
+
+        import json
+
+        from google.oauth2 import service_account
+
+        json_acct_info = json.loads(function_to_get_json_creds())
+        credentials = service_account.Credentials.from_service_account_info(
+            json_acct_info)
+
+        scoped_credentials = credentials.with_scopes(
+            ['https://www.googleapis.com/auth/cloud-platform'])
+
+.. warning:: Private keys must be kept secret. If you expose your private key it
+    is recommended to revoke it immediately from the Google Cloud Console.
+
+.. _Credentials page of the Google Cloud Console:
+    https://console.cloud.google.com/apis/credentials
+
 
 Downscoped credentials
 ++++++++++++++++++++++