PubSub: Document how to choose the PubSub auth method

pubsub/README.rst

@@ -158,3 +158,36 @@ block the current thread until a given condition obtains:
 To learn more, consult the `subscriber documentation`_.
 
 .. _subscriber documentation: https://googleapis.github.io/google-cloud-python/latest/pubsub/subscriber/index.html
+
+
+Authentication
+^^^^^^^^^^^^^^
+
+It is possible to specify the authentication method to use with the Pub/Sub
+clients. This can be done by providing an explicit `Credentials`_ instance. Support
+for various authentication methods is available from the `google-auth`_ library.
+
+For example, to use JSON Web Tokens, provide a `google.auth.jwt.Credentials`_ instance:
+
+.. code-block:: python
+
+    import json
+    from google.auth import jwt
+
+    service_account_info = json.load(open("service-account-info.json"))
+    audience = "https://pubsub.googleapis.com/google.pubsub.v1.Subscriber"
+
+    credentials = jwt.Credentials.from_service_account_info(
+        service_account_info, audience=audience
+    )
+
+    subscriber = pubsub_v1.SubscriberClient(credentials=credentials)
+
+    # The same for the publisher, except that the "audience" claim needs to be adjusted
+    publisher_audience = "https://pubsub.googleapis.com/google.pubsub.v1.Publisher"
+    credentials_pub = credentials.with_claims(audience=publisher_audience) 
+    publisher = pubsub_v1.PublisherClient(credentials=credentials_pub)
+
+.. _Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.credentials.html#google.auth.credentials.Credentials
+.. _google-auth: https://google-auth.readthedocs.io/en/latest/index.html
+.. _google.auth.jwt.Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.jwt.html#google.auth.jwt.Credentials