1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
Authentication
**************
.. _Overview:
Overview
========
For a language agnostic overview of authentication on Google Cloud, see `Authentication Overview`_.
.. _Authentication Overview: https://cloud.google.com/docs/authentication
* **If you're running in a Google Virtual Machine Environment (Compute Engine, App Engine, Cloud Run, Cloud Functions)**,
authentication should "just work".
* **If you're developing locally**,
the easiest way to authenticate is using the `Google Cloud SDK`_:
.. code-block:: bash
$ gcloud auth application-default login
Note that this command generates credentials for client libraries. To authenticate the CLI itself, use:
.. code-block:: bash
$ gcloud auth login
Previously, ``gcloud auth login`` was used for both use cases. If
your ``gcloud`` installation does not support the new command,
please update it:
.. code-block:: bash
$ gcloud components update
.. _Google Cloud SDK: http://cloud.google.com/sdk
* **If you're running your application elsewhere**,
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/iam/docs/creating-managing-service-accounts#creating
Client-Provided Authentication
==============================
Every package uses a :class:`Client <google.cloud.client.Client>`
as a base for interacting with an API.
For example:
.. code-block:: python
from google.cloud import datastore
client = datastore.Client()
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 for credentials in your environment by following the
precedence outlined by :func:`google.auth.default`.
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:`~google.auth.credentials.Credentials` object suited to your environment.
After creation, you can pass it directly to a :class:`Client <google.cloud.client.Client>`:
.. code:: python
client = Client(credentials=credentials)
.. tip::
To create a credentials object, follow the `google-auth-guide`_.
.. _google-auth-guide: https://googleapis.dev/python/google-auth/latest/user-guide.html#service-account-private-key-files
Google Compute Engine Environment
---------------------------------
These credentials are used in Google Virtual Machine Environments.
This includes most App Engine runtimes, Compute Engine, Cloud
Functions, and Cloud Run.
To create
:class:`credentials <google.auth.compute_engine.Credentials>`:
.. code:: python
from google.auth import compute_engine
credentials = compute_engine.Credentials()
Service Accounts
----------------
A `service account`_ is stored in a JSON keyfile.
.. code:: python
from google.oauth2 import service_account
credentials = service_account.Credentials.from_service_account_file(
'/path/to/key.json')
A JSON string or dictionary:
.. code:: python
import json
from google.oauth2 import service_account
json_account_info = json.loads(...) # convert JSON to dictionary
credentials = service_account.Credentials.from_service_account_info(
json_account_info)
.. tip::
Previously the Google Cloud Console would issue a PKCS12/P12 key for your
service account. This library does not support that key format. You can
generate a new JSON key for the same service account from the console.
User Accounts (3-legged OAuth 2.0) with a refresh token
-------------------------------------------------------
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`_.
.. _OAuth 2.0: https://developers.google.com/identity/protocols/OAuth2
.. 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 ``google-cloud-*`` library.
The simplest way to use credentials from a user account is via
Application Default Credentials using ``gcloud auth login``
(as mentioned above) and :func:`google.auth.default`:
.. code:: python
import google.auth
credentials, project = google.auth.default()
This will still follow the :ref:`precedence <Precedence>`
described above,
so be sure none of the other possible environments conflict
with your user provided credentials.
Troubleshooting
===============
Setting up a Service Account
----------------------------
If your application is not running on a Google Virtual Machine Environment,
you need a Service Account. See `Creating a Service Account`_.
.. _Creating a Service Account: https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating
Using Google Compute Engine
---------------------------
If your code is running on Google Compute Engine,
using the inferred Google `Application Default Credentials`_
will be sufficient for retrieving credentials.
However, by default your credentials may not grant you
access to the services you intend to use.
Be sure when you `set up the GCE instance`_,
you add the correct scopes for the APIs you want to access:
* **All APIs**
* ``https://www.googleapis.com/auth/cloud-platform``
* ``https://www.googleapis.com/auth/cloud-platform.read-only``
For scopes for specific APIs see `OAuth 2.0 Scopes for Google APIs`_
.. _set up the GCE instance: https://cloud.google.com/compute/docs/authentication#using
.. _OAuth 2.0 Scopes for Google APIS: https://developers.google.com/identity/protocols/oauth2/scopes
|
