blob: d43163fe12e07f0c423125b6ca1fe0c22ea26fd1 [file] [log] [blame]
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -08001User Guide
2==========
3
4.. currentmodule:: google.auth
5
6Credentials and account types
7-----------------------------
8
9:class:`~credentials.Credentials` are the means of identifying an application or
10user to a service or API. Credentials can be obtained with two different types
11of accounts: *service accounts* and *user accounts*.
12
13Credentials from service accounts identify a particular application. These types
14of credentials are used in server-to-server use cases, such as accessing a
15database. This library primarily focuses on service account credentials.
16
17Credentials from user accounts are obtained by asking the user to authorize
18access to their data. These types of credentials are used in cases where your
19application needs access to a user's data in another service, such as accessing
20a user's documents in Google Drive. This library provides no support for
21obtaining user credentials, but does provide limited support for using user
22credentials.
23
24Obtaining credentials
25---------------------
26
27.. _application-default:
28
29Application default credentials
30+++++++++++++++++++++++++++++++
31
32`Google Application Default Credentials`_ abstracts authentication across the
33different Google Cloud Platform hosting environments. When running on any Google
34Cloud hosting environment or when running locally with the `Google Cloud SDK`_
35installed, :func:`default` can automatically determine the credentials from the
36environment::
37
38 import google.auth
39
40 credentials, project = google.auth.default()
41
42If your application requires specific scopes::
43
44 credentials, project = google.auth.default(
45 scopes=['https://www.googleapis.com/auth/cloud-platform'])
46
47.. _Google Application Default Credentials:
48 https://developers.google.com/identity/protocols/
49 application-default-credentials
50.. _Google Cloud SDK: https://cloud.google.com/sdk
51
52
53Service account private key files
54+++++++++++++++++++++++++++++++++
55
56A service account private key file can be used to obtain credentials for a
57service account. You can create a private key using the `Credentials page of the
58Google Cloud Console`_. Once you have a private key you can either obtain
Alan Yee0958d7a2019-07-25 16:22:56 -070059credentials one of three ways:
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -080060
611. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full
62 path to your service account private key file
63
64 .. code-block:: bash
65
66 $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
67
68 Then, use :ref:`application default credentials <application-default>`.
69 :func:`default` checks for the ``GOOGLE_APPLICATION_CREDENTIALS``
70 environment variable before all other checks, so this will always use the
71 credentials you explicitly specify.
72
732. Use :meth:`service_account.Credentials.from_service_account_file
74 <google.oauth2.service_account.Credentials.from_service_account_file>`::
75
76 from google.oauth2 import service_account
77
78 credentials = service_account.Credentials.from_service_account_file(
79 '/path/to/key.json')
80
81 scoped_credentials = credentials.with_scopes(
82 ['https://www.googleapis.com/auth/cloud-platform'])
83
Alan Yee0958d7a2019-07-25 16:22:56 -0700843. Use :meth:`service_account.Credentials.from_service_account_info
85 <google.oauth2.service_account.Credentials.from_service_account_info>`::
86
87 import json
88
89 from google.oauth2 import service_account
90
91 json_acct_info = json.loads(function_to_get_json_creds())
92 credentials = service_account.Credentials.from_service_account_info(
93 json_acct_info)
94
95 scoped_credentials = credentials.with_scopes(
96 ['https://www.googleapis.com/auth/cloud-platform'])
97
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -080098.. warning:: Private keys must be kept secret. If you expose your private key it
99 is recommended to revoke it immediately from the Google Cloud Console.
100
101.. _Credentials page of the Google Cloud Console:
102 https://console.cloud.google.com/apis/credentials
103
104Compute Engine, Container Engine, and the App Engine flexible environment
105+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
106
107Applications running on `Compute Engine`_, `Container Engine`_, or the `App
108Engine flexible environment`_ can obtain credentials provided by `Compute
109Engine service accounts`_. When running on these platforms you can obtain
110credentials for the service account one of two ways:
111
1121. Use :ref:`application default credentials <application-default>`.
113 :func:`default` will automatically detect if these credentials are available.
114
1152. Use :class:`compute_engine.Credentials`::
116
117 from google.auth import compute_engine
118
119 credentials = compute_engine.Credentials()
120
121.. _Compute Engine: https://cloud.google.com/compute
122.. _Container Engine: https://cloud.google.com/container-engine
123.. _App Engine flexible environment:
124 https://cloud.google.com/appengine/docs/flexible/
125.. _Compute Engine service accounts:
126 https://cloud.google.com/compute/docs/access/service-accounts
127
128The App Engine standard environment
129+++++++++++++++++++++++++++++++++++
130
131Applications running on the `App Engine standard environment`_ can obtain
132credentials provided by the `App Engine App Identity API`_. You can obtain
133credentials one of two ways:
134
1351. Use :ref:`application default credentials <application-default>`.
136 :func:`default` will automatically detect if these credentials are available.
137
1382. Use :class:`app_engine.Credentials`::
139
140 from google.auth import app_engine
141
142 credentials = app_engine.Credentials()
143
Hiranya Jayathilaka22d90942017-07-17 09:08:49 -0700144In order to make authenticated requests in the App Engine environment using the
145credentials and transports provided by this library, you need to follow a few
146additional steps:
147
148#. If you are using the :mod:`google.auth.transport.requests` transport, vendor
Rohan Talipb61cecd2018-05-29 08:48:25 -0700149 in the `requests-toolbelt`_ library into your app, and enable the App Engine
Hiranya Jayathilaka22d90942017-07-17 09:08:49 -0700150 monkeypatch. Refer `App Engine documentation`_ for more details on this.
Rohan Talipb61cecd2018-05-29 08:48:25 -0700151#. To make HTTPS calls, enable the ``ssl`` library for your app by adding the
Hiranya Jayathilaka22d90942017-07-17 09:08:49 -0700152 following configuration to the ``app.yaml`` file::
153
154 libraries:
155 - name: ssl
156 version: latest
157
Rohan Talipb61cecd2018-05-29 08:48:25 -0700158#. Enable billing for your App Engine project. Then enable socket support for
Hiranya Jayathilaka22d90942017-07-17 09:08:49 -0700159 your app. This can be achieved by setting an environment variable in the
160 ``app.yaml`` file::
161
162 env_variables:
163 GAE_USE_SOCKETS_HTTPLIB : 'true'
164
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800165.. _App Engine standard environment:
166 https://cloud.google.com/appengine/docs/python
167.. _App Engine App Identity API:
168 https://cloud.google.com/appengine/docs/python/appidentity/
Hiranya Jayathilaka22d90942017-07-17 09:08:49 -0700169.. _requests-toolbelt:
170 https://toolbelt.readthedocs.io/en/latest/
171.. _App Engine documentation:
172 https://cloud.google.com/appengine/docs/standard/python/issue-requests
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800173
174User credentials
175++++++++++++++++
176
177User credentials are typically obtained via `OAuth 2.0`_. This library does not
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800178provide any direct support for *obtaining* user credentials, however, you can
179use user credentials with this library. You can use libraries such as
180`oauthlib`_ to obtain the access token. After you have an access token, you
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800181can create a :class:`google.oauth2.credentials.Credentials` instance::
182
183 import google.oauth2.credentials
184
185 credentials = google.oauth2.credentials.Credentials(
186 'access_token')
187
188If you obtain a refresh token, you can also specify the refresh token and token
189URI to allow the credentials to be automatically refreshed::
190
191 credentials = google.oauth2.credentials.Credentials(
192 'access_token',
193 refresh_token='refresh_token',
194 token_uri='token_uri',
195 client_id='client_id',
196 client_secret='client_secret')
197
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800198
Jon Wayne Parrottd47281b2017-03-22 13:45:26 -0700199There is a separate library, `google-auth-oauthlib`_, that has some helpers
200for integrating with `requests-oauthlib`_ to provide support for obtaining
201user credentials. You can use
202:func:`google_auth_oauthlib.helpers.credentials_from_session` to obtain
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800203:class:`google.oauth2.credentials.Credentials` from a
204:class:`requests_oauthlib.OAuth2Session` as above::
205
Jon Wayne Parrottd47281b2017-03-22 13:45:26 -0700206 from google_auth_oauthlib.helpers import credentials_from_session
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800207
Jon Wayne Parrottd47281b2017-03-22 13:45:26 -0700208 google_auth_credentials = credentials_from_session(oauth2session)
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800209
Jon Wayne Parrottd47281b2017-03-22 13:45:26 -0700210You can also use :class:`google_auth_oauthlib.flow.Flow` to perform the OAuth
2112.0 Authorization Grant Flow to obtain credentials using `requests-oauthlib`_.
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800212
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800213.. _OAuth 2.0:
214 https://developers.google.com/identity/protocols/OAuth2
215.. _oauthlib:
216 https://oauthlib.readthedocs.io/en/latest/
Jon Wayne Parrottd47281b2017-03-22 13:45:26 -0700217.. _google-auth-oauthlib:
218 https://pypi.python.org/pypi/google-auth-oauthlib
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800219.. _requests-oauthlib:
220 https://requests-oauthlib.readthedocs.io/en/latest/
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800221
salrashid1231fbc6792018-11-09 11:05:34 -0800222Impersonated credentials
223++++++++++++++++++++++++
224
225Impersonated Credentials allows one set of credentials issued to a user or service account
Tianzi Cai40865432019-03-29 11:12:37 -0700226to impersonate another. The source credentials must be granted
227the "Service Account Token Creator" IAM role. ::
salrashid1231fbc6792018-11-09 11:05:34 -0800228
229 from google.auth import impersonated_credentials
230
231 target_scopes = ['https://www.googleapis.com/auth/devstorage.read_only']
232 source_credentials = service_account.Credentials.from_service_account_file(
233 '/path/to/svc_account.json',
234 scopes=target_scopes)
235
236 target_credentials = impersonated_credentials.Credentials(
237 source_credentials=source_credentials,
238 target_principal='impersonated-account@_project_.iam.gserviceaccount.com',
239 target_scopes=target_scopes,
240 lifetime=500)
241 client = storage.Client(credentials=target_credentials)
242 buckets = client.list_buckets(project='your_project')
243 for bucket in buckets:
244 print bucket.name
245
246
247In the example above `source_credentials` does not have direct access to list buckets
248in the target project. Using `ImpersonatedCredentials` will allow the source_credentials
Tianzi Cai40865432019-03-29 11:12:37 -0700249to assume the identity of a target_principal that does have access.
salrashid1231fbc6792018-11-09 11:05:34 -0800250
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800251Making authenticated requests
252-----------------------------
253
254Once you have credentials you can attach them to a *transport*. You can then
255use this transport to make authenticated requests to APIs. google-auth supports
256several different transports. Typically, it's up to your application or an
257opinionated client library to decide which transport to use.
258
259Requests
260++++++++
261
262The recommended HTTP transport is :mod:`google.auth.transport.requests` which
263uses the `Requests`_ library. To make authenticated requests using Requests
264you use a custom `Session`_ object::
265
266 from google.auth.transport.requests import AuthorizedSession
267
268 authed_session = AuthorizedSession(credentials)
269
270 response = authed_session.get(
271 'https://www.googleapis.com/storage/v1/b')
272
273.. _Requests: http://docs.python-requests.org/en/master/
274.. _Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects
275
276urllib3
277+++++++
278
279:mod:`urllib3` is the underlying HTTP library used by Requests and can also be
280used with google-auth. urllib3's interface isn't as high-level as Requests but
281it can be useful in situations where you need more control over how HTTP
282requests are made. To make authenticated requests using urllib3 create an
283instance of :class:`google.auth.transport.urllib3.AuthorizedHttp`::
284
285 from google.auth.transport.urllib3 import AuthorizedHttp
286
287 authed_http = AuthorizedHttp(credentials)
288
289 response = authed_http.request(
290 'GET', 'https://www.googleapis.com/storage/v1/b')
291
292You can also construct your own :class:`urllib3.PoolManager` instance and pass
293it to :class:`~google.auth.transport.urllib3.AuthorizedHttp`::
294
295 import urllib3
296
297 http = urllib3.PoolManager()
298 authed_http = AuthorizedHttp(credentials, http)
299
300gRPC
301++++
302
303`gRPC`_ is an RPC framework that uses `Protocol Buffers`_ over `HTTP 2.0`_.
304google-auth can provide `Call Credentials`_ for gRPC. The easiest way to do
305this is to use google-auth to create the gRPC channel::
306
307 import google.auth.transport.grpc
308 import google.auth.transport.requests
309
310 http_request = google.auth.transport.requests.Request()
311
312 channel = google.auth.transport.grpc.secure_authorized_channel(
Jon Wayne Parrott840b3ac2016-11-10 12:07:51 -0800313 credentials, http_request, 'pubsub.googleapis.com:443')
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800314
315.. note:: Even though gRPC is its own transport, you still need to use one of
316 the other HTTP transports with gRPC. The reason is that most credential
317 types need to make HTTP requests in order to refresh their access token.
318 The sample above uses the Requests transport, but any HTTP transport can
319 be used. Additionally, if you know that your credentials do not need to
320 make HTTP requests in order to refresh (as is the case with
321 :class:`jwt.Credentials`) then you can specify ``None``.
322
323Alternatively, you can create the channel yourself and use
324:class:`google.auth.transport.grpc.AuthMetadataPlugin`::
325
326 import grpc
327
328 metadata_plugin = AuthMetadataPlugin(credentials, http_request)
329
330 # Create a set of grpc.CallCredentials using the metadata plugin.
331 google_auth_credentials = grpc.metadata_call_credentials(
332 metadata_plugin)
333
334 # Create SSL channel credentials.
335 ssl_credentials = grpc.ssl_channel_credentials()
336
337 # Combine the ssl credentials and the authorization credentials.
338 composite_credentials = grpc.composite_channel_credentials(
339 ssl_credentials, google_auth_credentials)
340
341 channel = grpc.secure_channel(
342 'pubsub.googleapis.com:443', composite_credentials)
343
344You can use this channel to make a gRPC stub that makes authenticated requests
345to a gRPC service::
346
347 from google.pubsub.v1 import pubsub_pb2
348
349 pubsub = pubsub_pb2.PublisherStub(channel)
350
351 response = pubsub.ListTopics(
352 pubsub_pb2.ListTopicsRequest(project='your-project'))
353
354
355.. _gRPC: http://www.grpc.io/
356.. _Protocol Buffers:
357 https://developers.google.com/protocol-buffers/docs/overview
358.. _HTTP 2.0:
359 http://www.grpc.io/docs/guides/wire.html
360.. _Call Credentials:
361 http://www.grpc.io/docs/guides/auth.html