Add support for imersonated_credentials.Sign, IDToken (#348)
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index d43163f..0abe160 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -241,13 +241,91 @@
client = storage.Client(credentials=target_credentials)
buckets = client.list_buckets(project='your_project')
for bucket in buckets:
- print bucket.name
+ 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.
+Identity Tokens
++++++++++++++++
+
+`Google OpenID Connect`_ tokens are avaiable through :mod:`Service Account <google.oauth2.service_account>`,
+:mod:`Impersonated <google.auth.impersonated_credentials>`,
+and :mod:`Compute Engine <google.auth.compute_engine>`. These tokens can be used to
+authenticate against `Cloud Functions`_, `Cloud Run`_, a user service behind
+`Identity Aware Proxy`_ or any other service capable of verifying a `Google ID Token`_.
+
+ServiceAccount ::
+
+ from google.oauth2 import service_account
+
+ target_audience = 'https://example.com'
+
+ creds = service_account.IDTokenCredentials.from_service_account_file(
+ '/path/to/svc.json',
+ target_audience=target_audience)
+
+
+Compute ::
+
+ from google.auth import compute_engine
+ import google.auth.transport.requests
+
+ target_audience = 'https://example.com'
+
+ request = google.auth.transport.requests.Request()
+ creds = compute_engine.IDTokenCredentials(request,
+ target_audience=target_audience)
+
+Impersonated ::
+
+ from google.auth import impersonated_credentials
+
+ # get target_credentials from a source_credential
+
+ target_audience = 'https://example.com'
+
+ creds = impersonated_credentials.IDTokenCredentials(
+ target_credentials,
+ target_audience=target_audience)
+
+IDToken verification can be done for various type of IDTokens using the :class:`google.oauth2.id_token` module
+
+A sample end-to-end flow using an ID Token against a Cloud Run endpoint maybe ::
+
+ from google.oauth2 import id_token
+ from google.oauth2 import service_account
+ import google.auth
+ import google.auth.transport.requests
+ from google.auth.transport.requests import AuthorizedSession
+
+ target_audience = 'https://your-cloud-run-app.a.run.app'
+ url = 'https://your-cloud-run-app.a.run.app'
+
+ creds = service_account.IDTokenCredentials.from_service_account_file(
+ '/path/to/svc.json', target_audience=target_audience)
+
+ authed_session = AuthorizedSession(creds)
+
+ # make authenticated request and print the response, status_code
+ resp = authed_session.get(url)
+ print(resp.status_code)
+ print(resp.text)
+
+ # to verify an ID Token
+ request = google.auth.transport.requests.Request()
+ token = creds.token
+ print(token)
+ print(id_token.verify_token(token,request))
+
+.. _Cloud Functions: https://cloud.google.com/functions/
+.. _Cloud Run: https://cloud.google.com/run/
+.. _Identity Aware Proxy: https://cloud.google.com/iap/
+.. _Google OpenID Connect: https://developers.google.com/identity/protocols/OpenIDConnect
+.. _Google ID Token: https://developers.google.com/identity/protocols/OpenIDConnect#validatinganidtoken
+
Making authenticated requests
-----------------------------