Merge pull request #1088 from dhermes/auth-add-non-default-behavior

Adding section about order used for app. default creds.

docs/gcloud-auth.rst

@@ -1,5 +1,5 @@
 Authentication
---------------
+**************
 
 .. _Overview:
 
@@ -20,13 +20,15 @@ Overview
 
 
 *   **If you're running your application elsewhere**,
-    you should download a service account JSON keyfile
+    you should download a `service account`_ JSON keyfile
     and point to it using an environment variable:
 
     .. code-block:: bash
 
         $ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
 
+.. _service account: https://cloud.google.com/storage/docs/authentication#generating-a-private-key
+
 Client-Provided Authentication
 ==============================
 
@@ -43,3 +45,43 @@ instructions in the :ref:`Overview`. The credentials are inferred from your
 local environment by using Google `Application Default Credentials`_.
 
 .. _Application Default Credentials: https://developers.google.com/identity/protocols/application-default-credentials
+
+Credential Discovery Precedence
+-------------------------------
+
+When loading the `Application Default Credentials`_, the library will check
+properties of your local environment in the following order
+
+#. Application running in Google App Engine
+#. JSON or PKCS12/P12 keyfile pointed to by
+   ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable
+#. Credentials provided by the Google Cloud SDK (via ``gcloud auth login``)
+#. Application running in Google Compute Engine
+
+Loading Credentials Explicitly
+------------------------------
+
+In addition, the
+:meth:`from_service_account_json() <gcloud.client.Client.from_service_account_json>`
+and
+:meth:`from_service_account_p12() <gcloud.client.Client.from_service_account_p12>`
+factories can be used if you know the specific type of credentials you'd
+like to use.
+
+.. code:: python
+
+    client = Client.from_service_account_json('/path/to/keyfile.json')
+
+.. tip::
+
+    Unless you have an explicit reason to use a PKCS12 key for your
+    service account, we recommend using a JSON key.
+
+Finally, if you are **familiar** with the `oauth2client`_ library, you can
+create a ``credentials`` object and pass it directly:
+
+.. code:: python
+
+    client = Client(credentials=credentials)
+
+.. _oauth2client: http://oauth2client.readthedocs.org/en/latest/