8000 Describing how to create credentials explicitly in auth doc. · googleapis/google-cloud-python@06f7ac6 · GitHub
[go: up one dir, main page]
Skip to content

Commit 06f7ac6

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 06f7ac6

File tree

1 file changed

+95
-19
lines changed

1 file changed

+95
-19
lines changed

‎docs/gcloud-auth.rst

Lines changed: 95 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -32,56 +32,132 @@ 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

4951
Credential Discovery Precedence
5052
-------------------------------
5153

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

5558
#. Application running in Google App Engine
5659
#. JSON or PKCS12/P12 keyfile pointed to by
5760
``GOOGLE_APPLICATION_CREDENTIALS`` environment variable
5861
#. Credentials provided by the Google Cloud SDK (via ``gcloud auth login``)
5962
#. Application running in Google Compute Engine
6063

61-
Loading Credentials Explicitly
62-
------------------------------
64+
Explicit Credentials
65+
====================
6366

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

71130
.. code:: python
72131
73132
client = Client.from_service_account_json('/path/to/keyfile.json')
74133
75134
.. tip::
76135

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

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

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

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

87-
.. _oauth2client: http://oauth2client.readthedocs.org/en/latest/
150+
.. tip::
151+
152+
A production application should **use a service account**,
153+
but you may wish to use your own personal user account when first
154+
getting started with the ``gcloud-python`` library.
155+
156+
This is only supported via Application Default Credentials using
157+
``gcloud auth login`` as mentioned above.
158+
To create these credentials directly:
159+
160+
.. code:: python
161+
162+
from oauth2client.client import GoogleCredentials
163+
credentials = GoogleCredentials.get_application_default()

0 commit comments

Comments
 (0)
0