Skip to content

Commit 0cc3a19

Browse files
dhermesdhermes
committed
Describing how to create credentials explicitly in auth doc.
Also moving the from_service_account_* factory descriptions into the newly added sections.
1 parent b3ee149 commit 0cc3a19

File tree

1 file changed

+114
-19
lines changed

1 file changed

+114
-19
lines changed

‎docs/gcloud-auth.rst‎

Lines changed: 114 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -32,56 +32,151 @@ Overview
3232
Client-Provided Authentication
3333
==============================
3434

35-
Every package uses a :class:`Client <gcloud.client.Client>` as a base
36-
for interacting with an API. For example:
35+
Every package uses a :class:`Client <gcloud.client.Client>`
36+
as a base for interacting with an API.
37+
For example:
3738

3839
.. code-block:: python
3940
4041
from gcloud import datastore
4142
client = datastore.Client()
4243
43-
Passing no arguments at all will "just work" if you've following the
44-
instructions in the :ref:`Overview`. The credentials are inferred from your
45-
local environment by using Google `Application Default Credentials`_.
44+
Passing no arguments at all will "just work" if you've followed the
45+
instructions in the :ref:`Overview`.
46+
The credentials are inferred from your local environment by using
47+
Google `Application Default Credentials`_.
4648

4749
.. _Application Default Credentials: https://developers.google.com/identity/protocols/application-default-credentials
4850

51+
.. _Precedence:
52+
4953
Credential Discovery Precedence
5054
-------------------------------
5155

52-
When loading the `Application Default Credentials`_, the library will check
53-
properties of your local environment in the following order
56+
When loading the `Application Default Credentials`_,
57+
the library will check properties of your local environment
58+
in the following order:
5459

5560
#. Application running in Google App Engine
5661
#. JSON or PKCS12/P12 keyfile pointed to by
5762
``GOOGLE_APPLICATION_CREDENTIALS`` environment variable
5863
#. Credentials provided by the Google Cloud SDK (via ``gcloud auth login``)
5964
#. Application running in Google Compute Engine
6065

61-
Loading Credentials Explicitly
62-
------------------------------
66+
Explicit Credentials
67+
====================
68+
69+
The Application Default Credentials discussed above can be useful
70+
if your code needs to run in many different environments or
71+
if you just don't want authentication to be a focus in your code.
72+
73+
However, you may want to be explicit because
74+
75+
* your code will only run in one place
76+
* you may have code which needs to be run as a specific service account
77+
every time (rather than with the locally inferred credentials)
78+
* you may want to use two separate accounts to simultaneously access data
79+
from different projects
80+
81+
In these situations, you can create an explicit
82+
:class:`Credentials <oauth2client.client.Credentials>` object suited to your
83+
environment.
84+
After creation,
85+
you can pass it directly to a :class:`Client <gcloud.client.Client>`:
86+
87+
.. code:: python
88+
89+
client = Client(credentials=credentials)
6390
64-
In addition, the
91+
Google App Engine Environment
92+
-----------------------------
93+
94+
To create :class:`credentials <oauth2client.appengine.AppAssertionCredentials>`
95+
just for Google App Engine:
96+
97+
.. code:: python
98+
99+
from oauth2client.appengine import AppAssertionCredentials
100+
credentials = AppAssertionCredentials([])
101+
102+
Google Compute Engine Environment
103+
---------------------------------
104+
105+
To create :class:`credentials <oauth2client.gce.AppAssertionCredentials>`
106+
just for Google Compute Engine:
107+
108+
.. code:: python
109+
110+
from oauth2client.gce import AppAssertionCredentials
111+
credentials = AppAssertionCredentials([])
112+
113+
Service Accounts
114+
----------------
115+
116+
A `service account`_ can be used with both a JSON keyfile and
117+
a PKCS12/P12 keyfile.
118+
119+
Directly creating ``credentials`` in `oauth2client`_ for a service
120+
account is a rather complex process,
121+
so as a convenience, the
65122
:meth:`from_service_account_json() <gcloud.client.Client.from_service_account_json>`
66123
and
67124
:meth:`from_service_account_p12() <gcloud.client.Client.from_service_account_p12>`
68-
factories can be used if you know the specific type of credentials you'd
69-
like to use.
125+
factories are provided to create a :class:`Client <gcloud.client.Client>` with
126+
service account credentials.
127+
128+
.. _oauth2client: http://oauth2client.readthedocs.org/en/latest/
129+
130+
For example, with a JSON keyfile:
70131

71132
.. code:: python
72133
73134
client = Client.from_service_account_json('/path/to/keyfile.json')
74135
75136
.. tip::
76137

77-
Unless you have an explicit reason to use a PKCS12 key for your
78-
service account, we recommend using a JSON key.
138+
Unless you have a specific reason to use a PKCS12/P12 key for your
139+
service account,
140+
we recommend using a JSON key.
79141

80-
Finally, if you are **familiar** with the `oauth2client`_ library, you can
81-
create a ``credentials`` object and pass it directly:
142+
User Accounts (3-legged OAuth 2.0) with a refresh token
143+
-------------------------------------------------------
82144

83-
.. code:: python
145+
The majority of cases are intended to authenticate machines or
146+
workers rather than actual user accounts. However, it's also
147+
possible to call Google Cloud APIs with a user account via
148+
`OAuth 2.0`_.
84149

85-
client = Client(credentials=credentials)
150+
.. _OAuth 2.0: https://developers.google.com/identity/protocols/OAuth2
86151

87-
.. _oauth2client: http://oauth2client.readthedocs.org/en/latest/
152+
.. tip::
153+
154+
A production application should **use a service account**,
155+
but you may wish to use your own personal user account when first
156+
getting started with the ``gcloud-python`` library.
157+
158+
The simplest way to use credentials from a user account is via
159+
Application Default Credentials using ``gcloud auth login``
160+
(as mentioned above):
161+
162+
.. code:: python
163+
164+
from oauth2client.client import GoogleCredentials
165+
credentials = GoogleCredentials.get_application_default()
166+
167+
This will still follow the :ref:`precedence <Precedence>`
168+
described above,
169+
so be sure none of the other possible environments conflict
170+
with your user provided credentials.
171+
172+
Advanced users of `oauth2client`_ can also use custom flows to
173+
create credentials using `client secrets`_ or using a
174+
`webserver flow`_.
175+
After creation, :class:`Credentials <oauth2client.client.Credentials>`
176+
can be serialized with
177+
:meth:`to_json() <oauth2client.client.Credentials.to_json>`
178+
and stored in a file and then and deserialized with
179+
:meth:`from_json() <oauth2client.client.Credentials.from_json>`.
180+
181+
.. _client secrets: https://developers.google.com/api-client-library/python/guide/aaa_oauth#flow_from_clientsecrets
182+
.. _webserver flow: https://developers.google.com/api-client-library/python/guide/aaa_oauth#OAuth2WebServerFlow

0 commit comments

Comments
 (0)