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