Add google.auth.impersonated_credentials (#299)
diff --git a/docs/index.rst b/docs/index.rst
index 56e3eca..1eb3d86 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,7 @@
- Support for signing and verifying :mod:`JWTs <google.auth.jwt>`.
- Support for verifying and decoding :mod:`ID Tokens <google.oauth2.id_token>`.
- Support for Google :mod:`Service Account credentials <google.oauth2.service_account>`.
+- Support for Google :mod:`Impersonated Credentials <google.auth.impersonated_credentials>`.
- Support for :mod:`Google Compute Engine credentials <google.auth.compute_engine>`.
- Support for :mod:`Google App Engine standard credentials <google.auth.app_engine>`.
- Support for various transports, including
diff --git a/docs/reference/google.auth.impersonated_credentials.rst b/docs/reference/google.auth.impersonated_credentials.rst
new file mode 100644
index 0000000..653708e
--- /dev/null
+++ b/docs/reference/google.auth.impersonated_credentials.rst
@@ -0,0 +1,7 @@
+google.auth.impersonated\_credentials module
+============================================
+
+.. automodule:: google.auth.impersonated_credentials
+ :members:
+ :inherited-members:
+ :show-inheritance:
diff --git a/docs/reference/google.auth.rst b/docs/reference/google.auth.rst
index 244d0bb..bc6740b 100644
--- a/docs/reference/google.auth.rst
+++ b/docs/reference/google.auth.rst
@@ -25,5 +25,6 @@
google.auth.environment_vars
google.auth.exceptions
google.auth.iam
+ google.auth.impersonated_credentials
google.auth.jwt
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 060d9b8..7587917 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -205,6 +205,35 @@
.. _requests-oauthlib:
https://requests-oauthlib.readthedocs.io/en/latest/
+Impersonated credentials
+++++++++++++++++++++++++
+
+Impersonated Credentials allows one set of credentials issued to a user or service account
+to impersonate another. The target service account must grant the source credential
+the "Service Account Token Creator" IAM role::
+
+ from google.auth import impersonated_credentials
+
+ target_scopes = ['https://www.googleapis.com/auth/devstorage.read_only']
+ source_credentials = service_account.Credentials.from_service_account_file(
+ '/path/to/svc_account.json',
+ scopes=target_scopes)
+
+ target_credentials = impersonated_credentials.Credentials(
+ source_credentials=source_credentials,
+ target_principal='impersonated-account@_project_.iam.gserviceaccount.com',
+ target_scopes=target_scopes,
+ lifetime=500)
+ client = storage.Client(credentials=target_credentials)
+ buckets = client.list_buckets(project='your_project')
+ for bucket in buckets:
+ print bucket.name
+
+
+In the example above `source_credentials` does not have direct access to list buckets
+in the target project. Using `ImpersonatedCredentials` will allow the source_credentials
+to assume the identity of a target_principal that does have access
+
Making authenticated requests
-----------------------------