From 0cc3a192a6ed2a8a0ec97c9d706a3fae47a34d3e Mon Sep 17 00:00:00 2001 From: Danny Hermes Date: Wed, 26 Aug 2015 12:51:47 -0700 Subject: [PATCH] Describing how to create credentials explicitly in auth doc. Also moving the from_service_account_* factory descriptions into the newly added sections. --- docs/gcloud-auth.rst | 133 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 114 insertions(+), 19 deletions(-) diff --git a/docs/gcloud-auth.rst b/docs/gcloud-auth.rst index e10edb92c7ce..ab7949990acc 100644 --- a/docs/gcloud-auth.rst +++ b/docs/gcloud-auth.rst @@ -32,25 +32,30 @@ Overview Client-Provided Authentication ============================== -Every package uses a :class:`Client ` as a base -for interacting with an API. For example: +Every package uses a :class:`Client ` +as a base for interacting with an API. +For example: .. code-block:: python from gcloud import datastore client = datastore.Client() -Passing no arguments at all will "just work" if you've following the -instructions in the :ref:`Overview`. The credentials are inferred from your -local environment by using Google `Application Default Credentials`_. +Passing no arguments at all will "just work" if you've followed the +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 +.. _Precedence: + Credential Discovery Precedence ------------------------------- -When loading the `Application Default Credentials`_, the library will check -properties of your local environment in the following order +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 @@ -58,15 +63,71 @@ properties of your local environment in the following order #. Credentials provided by the Google Cloud SDK (via ``gcloud auth login``) #. Application running in Google Compute Engine -Loading Credentials Explicitly ------------------------------- +Explicit Credentials +==================== + +The Application Default Credentials discussed above can be useful +if your code needs to run in many different environments or +if you just don't want authentication to be a focus in your code. + +However, you may want to be explicit because + +* your code will only run in one place +* you may have code which needs to be run as a specific service account + every time (rather than with the locally inferred credentials) +* you may want to use two separate accounts to simultaneously access data + from different projects + +In these situations, you can create an explicit +:class:`Credentials ` object suited to your +environment. +After creation, +you can pass it directly to a :class:`Client `: + +.. code:: python + + client = Client(credentials=credentials) -In addition, the +Google App Engine Environment +----------------------------- + +To create :class:`credentials ` +just for Google App Engine: + +.. code:: python + + from oauth2client.appengine import AppAssertionCredentials + credentials = AppAssertionCredentials([]) + +Google Compute Engine Environment +--------------------------------- + +To create :class:`credentials ` +just for Google Compute Engine: + +.. code:: python + + from oauth2client.gce import AppAssertionCredentials + credentials = AppAssertionCredentials([]) + +Service Accounts +---------------- + +A `service account`_ can be used with both a JSON keyfile and +a PKCS12/P12 keyfile. + +Directly creating ``credentials`` in `oauth2client`_ for a service +account is a rather complex process, +so as a convenience, the :meth:`from_service_account_json() ` and :meth:`from_service_account_p12() ` -factories can be used if you know the specific type of credentials you'd -like to use. +factories are provided to create a :class:`Client ` with +service account credentials. + +.. _oauth2client: http://oauth2client.readthedocs.org/en/latest/ + +For example, with a JSON keyfile: .. code:: python @@ -74,14 +135,48 @@ like to use. .. tip:: - Unless you have an explicit reason to use a PKCS12 key for your - service account, we recommend using a JSON key. + Unless you have a specific reason to use a PKCS12/P12 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: +User Accounts (3-legged OAuth 2.0) with a refresh token +------------------------------------------------------- -.. code:: python +The majority of cases are intended to authenticate machines or +workers rather than actual user accounts. However, it's also +possible to call Google Cloud APIs with a user account via +`OAuth 2.0`_. - client = Client(credentials=credentials) +.. _OAuth 2.0: https://developers.google.com/identity/protocols/OAuth2 -.. _oauth2client: http://oauth2client.readthedocs.org/en/latest/ +.. tip:: + + A production application should **use a service account**, + but you may wish to use your own personal user account when first + getting started with the ``gcloud-python`` library. + +The simplest way to use credentials from a user account is via +Application Default Credentials using ``gcloud auth login`` +(as mentioned above): + +.. code:: python + + from oauth2client.client import GoogleCredentials + credentials = GoogleCredentials.get_application_default() + +This will still follow the :ref:`precedence ` +described above, +so be sure none of the other possible environments conflict +with your user provided credentials. + +Advanced users of `oauth2client`_ can also use custom flows to +create credentials using `client secrets`_ or using a +`webserver flow`_. +After creation, :class:`Credentials ` +can be serialized with +:meth:`to_json() ` +and stored in a file and then and deserialized with +:meth:`from_json() `. + +.. _client secrets: https://developers.google.com/api-client-library/python/guide/aaa_oauth#flow_from_clientsecrets +.. _webserver flow: https://developers.google.com/api-client-library/python/guide/aaa_oauth#OAuth2WebServerFlow