Skip to content

Commit 2b1a93b

Browse files
author
Jon Wayne Parrott
authored
Update auth documentation (googleapis#2801)
1 parent dc95e51 commit 2b1a93b

File tree

1 file changed

+30
-40
lines changed

1 file changed

+30
-40
lines changed

‎docs/google-cloud-auth.rst‎

Lines changed: 30 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -68,14 +68,8 @@ Credential Discovery Precedence
6868
-------------------------------
6969

7070
When loading the `Application Default Credentials`_,
71-
the library will check properties of your local environment
72-
in the following order:
73-
74-
#. Application running in Google App Engine
75-
#. JSON or PKCS12/P12 keyfile pointed to by
76-
``GOOGLE_APPLICATION_CREDENTIALS`` environment variable
77-
#. Credentials provided by the Google Cloud SDK (via ``gcloud auth login``)
78-
#. Application running in Google Compute Engine
71+
the library will check for credentials in your environment by following the
72+
precedence outlined by :func:`google.auth.default`.
7973

8074
Explicit Credentials
8175
====================
@@ -93,10 +87,9 @@ However, you may want to be explicit because
9387
from different projects
9488

9589
In these situations, you can create an explicit
96-
:class:`Credentials <oauth2client.client.Credentials>` object suited to your
97-
environment.
98-
After creation,
99-
you can pass it directly to a :class:`Client <google.cloud.client.Client>`:
90+
:class:`~google.auth.credentials.Credentials` object suited to your
91+
environment. After creation, you can pass it directly to a
92+
:class:`Client <google.cloud.client.Client>`:
10093

10194
.. code:: python
10295
@@ -106,43 +99,36 @@ Google App Engine Environment
10699
-----------------------------
107100

108101
To create
109-
:class:`credentials <oauth2client.contrib.appengine.AppAssertionCredentials>`
102+
:class:`credentials <google.auth.app_engine.Credentials>`
110103
just for Google App Engine:
111104

112105
.. code:: python
113106
114-
from oauth2client.contrib.appengine import AppAssertionCredentials
115-
credentials = AppAssertionCredentials([])
107+
from google.auth import app_engine
108+
credentials = app_engine.Credentials()
116109
117110
Google Compute Engine Environment
118111
---------------------------------
119112

120113
To create
121-
:class:`credentials <oauth2client.contrib.gce.AppAssertionCredentials>`
114+
:class:`credentials <google.auth.compute_engine.Credentials>`
122115
just for Google Compute Engine:
123116

124117
.. code:: python
125118
126-
from oauth2client.contrib.gce import AppAssertionCredentials
127-
credentials = AppAssertionCredentials([])
119+
from google.auth import compute_engine
120+
credentials = compute_engine.Credentials()
128121
129122
Service Accounts
130123
----------------
131124

132-
A `service account`_ can be used with both a JSON keyfile and
133-
a PKCS12/P12 keyfile.
125+
A `service account`_ is stored in a JSON keyfile.
134126

135-
Directly creating ``credentials`` in `oauth2client`_ for a service
136-
account is a rather complex process,
137-
so as a convenience, the
127+
The
138128
:meth:`from_service_account_json() <google.cloud.client.Client.from_service_account_json>`
139-
and
140-
:meth:`from_service_account_p12() <google.cloud.client.Client.from_service_account_p12>`
141-
factories are provided to create a :class:`Client <google.cloud.client.Client>` with
129+
factory can be used to create a :class:`Client <google.cloud.client.Client>` with
142130
service account credentials.
143131

144-
.. _oauth2client: http://oauth2client.readthedocs.io/en/latest/
145-
146132
For example, with a JSON keyfile:
147133

148134
.. code:: python
@@ -151,9 +137,9 @@ For example, with a JSON keyfile:
151137
152138
.. tip::
153139

154-
Unless you have a specific reason to use a PKCS12/P12 key for your
155-
service account,
156-
we recommend using a JSON key.
140+
Previously the Google Cloud Console would issue a PKCS12/P12 key for your
141+
service account. This library does not support that key format. You can
142+
generate a new JSON key for the same service account from the console.
157143

158144
User Accounts (3-legged OAuth 2.0) with a refresh token
159145
-------------------------------------------------------
@@ -173,12 +159,13 @@ possible to call Google Cloud APIs with a user account via
173159

174160
The simplest way to use credentials from a user account is via
175161
Application Default Credentials using ``gcloud auth login``
176-
(as mentioned above):
162+
(as mentioned above) and :func:`google.auth.default`:
177163

178164
.. code:: python
179165
180-
from oauth2client.client import GoogleCredentials
181-
credentials = GoogleCredentials.get_application_default()
166+
import google.auth
167+
168+
credentials, project = google.auth.default()
182169
183170
This will still follow the :ref:`precedence <Precedence>`
184171
described above,
@@ -192,10 +179,14 @@ After creation, :class:`Credentials <oauth2client.client.Credentials>`
192179
can be serialized with
193180
:meth:`to_json() <oauth2client.client.Credentials.to_json>`
194181
and stored in a file and then and deserialized with
195-
:meth:`from_json() <oauth2client.client.Credentials.from_json>`.
182+
:meth:`from_json() <oauth2client.client.Credentials.from_json>`. In order
183+
to use ``oauth2client``'s credentials with this library, you'll need to
184+
`convert them`_.
196185

186+
.. _oauth2client: https://github.com/Google/oauth2client.
197187
.. _client secrets: https://developers.google.com/api-client-library/python/guide/aaa_oauth#flow_from_clientsecrets
198188
.. _webserver flow: https://developers.google.com/api-client-library/python/guide/aaa_oauth#OAuth2WebServerFlow
189+
.. _convert them: http://google-auth.readthedocs.io/en/stable/user-guide.html#user-credentials
199190

200191
Troubleshooting
201192
===============
@@ -307,10 +298,12 @@ you add the correct scopes for the APIs you want to access:
307298
Advanced Customization
308299
======================
309300

310-
Though the ``google-cloud-python`` library defaults to using `oauth2client`_
301+
Though the ``google-cloud-python`` library defaults to using `google-auth`_
311302
to sign requests and ``httplib2`` for sending requests,
312303
it is not a strict requirement.
313304

305+
.. _google-auth: http://google-auth.readthedocs.io/en/stable/
306+
314307
The :class:`Client <google.cloud.client.Client>` constructor accepts an optional
315308
``http`` argument in place of a ``credentials`` object.
316309
If passed, all HTTP requests made by the client will use your
@@ -337,10 +330,7 @@ using the `requests`_ library.
337330
.. _custom HTTP class: https://github.com/GoogleCloudPlatform/google-cloud-python/issues/908#issuecomment-110811556
338331
.. _requests: http://www.python-requests.org/en/latest/
339332

340-
As for handling authentication on your own,
341-
it may be easiest just to re-use bits from ``oauth2client``.
342-
Unfortunately, these parts have a hard dependency on ``httplib2``.
343-
We hope to enable using `custom HTTP libraries`_ with ``oauth2client`` at
333+
We hope to enable using `custom HTTP libraries`_ with this library at
344334
some point.
345335

346336
.. _custom HTTP libraries: https://github.com/google/oauth2client/issues/128

0 commit comments

Comments
 (0)