blob: f4cf8309795c61008b92b36ccf826d0a361958d0 [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
59credentials one of two ways:
60
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
84.. warning:: Private keys must be kept secret. If you expose your private key it
85 is recommended to revoke it immediately from the Google Cloud Console.
86
87.. _Credentials page of the Google Cloud Console:
88 https://console.cloud.google.com/apis/credentials
89
90Compute Engine, Container Engine, and the App Engine flexible environment
91+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
92
93Applications running on `Compute Engine`_, `Container Engine`_, or the `App
94Engine flexible environment`_ can obtain credentials provided by `Compute
95Engine service accounts`_. When running on these platforms you can obtain
96credentials for the service account one of two ways:
97
981. Use :ref:`application default credentials <application-default>`.
99 :func:`default` will automatically detect if these credentials are available.
100
1012. Use :class:`compute_engine.Credentials`::
102
103 from google.auth import compute_engine
104
105 credentials = compute_engine.Credentials()
106
107.. _Compute Engine: https://cloud.google.com/compute
108.. _Container Engine: https://cloud.google.com/container-engine
109.. _App Engine flexible environment:
110 https://cloud.google.com/appengine/docs/flexible/
111.. _Compute Engine service accounts:
112 https://cloud.google.com/compute/docs/access/service-accounts
113
114The App Engine standard environment
115+++++++++++++++++++++++++++++++++++
116
117Applications running on the `App Engine standard environment`_ can obtain
118credentials provided by the `App Engine App Identity API`_. You can obtain
119credentials one of two ways:
120
1211. Use :ref:`application default credentials <application-default>`.
122 :func:`default` will automatically detect if these credentials are available.
123
1242. Use :class:`app_engine.Credentials`::
125
126 from google.auth import app_engine
127
128 credentials = app_engine.Credentials()
129
130.. _App Engine standard environment:
131 https://cloud.google.com/appengine/docs/python
132.. _App Engine App Identity API:
133 https://cloud.google.com/appengine/docs/python/appidentity/
134
135User credentials
136++++++++++++++++
137
138User credentials are typically obtained via `OAuth 2.0`_. This library does not
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800139provide any direct support for *obtaining* user credentials, however, you can
140use user credentials with this library. You can use libraries such as
141`oauthlib`_ to obtain the access token. After you have an access token, you
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800142can create a :class:`google.oauth2.credentials.Credentials` instance::
143
144 import google.oauth2.credentials
145
146 credentials = google.oauth2.credentials.Credentials(
147 'access_token')
148
149If you obtain a refresh token, you can also specify the refresh token and token
150URI to allow the credentials to be automatically refreshed::
151
152 credentials = google.oauth2.credentials.Credentials(
153 'access_token',
154 refresh_token='refresh_token',
155 token_uri='token_uri',
156 client_id='client_id',
157 client_secret='client_secret')
158
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800159
160This library has some helpers for integrating with `requests-oauthlib`_ to
161provide support for obtaining user credentials. You can use
162:func:`google.oauth2.oauthlib.credentials_from_session` to obtain
163:class:`google.oauth2.credentials.Credentials` from a
164:class:`requests_oauthlib.OAuth2Session` as above::
165
166 import google.oauth2.oauthlib
167
168 google_auth_credentials = google.oauth2.oauthlib.credentials_from_session(
169 oauth2session)
170
171You can also use :class:`google.oauth2.flow.Flow` to perform the OAuth 2.0
172Authorization Grant Flow to obtain credentials using `requests-oauthlib`_.
173
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800174.. _OAuth 2.0:
175 https://developers.google.com/identity/protocols/OAuth2
176.. _oauthlib:
177 https://oauthlib.readthedocs.io/en/latest/
Jon Wayne Parrott81701942017-03-01 14:03:38 -0800178.. _requests-oauthlib:
179 https://requests-oauthlib.readthedocs.io/en/latest/
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800180
181Making authenticated requests
182-----------------------------
183
184Once you have credentials you can attach them to a *transport*. You can then
185use this transport to make authenticated requests to APIs. google-auth supports
186several different transports. Typically, it's up to your application or an
187opinionated client library to decide which transport to use.
188
189Requests
190++++++++
191
192The recommended HTTP transport is :mod:`google.auth.transport.requests` which
193uses the `Requests`_ library. To make authenticated requests using Requests
194you use a custom `Session`_ object::
195
196 from google.auth.transport.requests import AuthorizedSession
197
198 authed_session = AuthorizedSession(credentials)
199
200 response = authed_session.get(
201 'https://www.googleapis.com/storage/v1/b')
202
203.. _Requests: http://docs.python-requests.org/en/master/
204.. _Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects
205
206urllib3
207+++++++
208
209:mod:`urllib3` is the underlying HTTP library used by Requests and can also be
210used with google-auth. urllib3's interface isn't as high-level as Requests but
211it can be useful in situations where you need more control over how HTTP
212requests are made. To make authenticated requests using urllib3 create an
213instance of :class:`google.auth.transport.urllib3.AuthorizedHttp`::
214
215 from google.auth.transport.urllib3 import AuthorizedHttp
216
217 authed_http = AuthorizedHttp(credentials)
218
219 response = authed_http.request(
220 'GET', 'https://www.googleapis.com/storage/v1/b')
221
222You can also construct your own :class:`urllib3.PoolManager` instance and pass
223it to :class:`~google.auth.transport.urllib3.AuthorizedHttp`::
224
225 import urllib3
226
227 http = urllib3.PoolManager()
228 authed_http = AuthorizedHttp(credentials, http)
229
230gRPC
231++++
232
233`gRPC`_ is an RPC framework that uses `Protocol Buffers`_ over `HTTP 2.0`_.
234google-auth can provide `Call Credentials`_ for gRPC. The easiest way to do
235this is to use google-auth to create the gRPC channel::
236
237 import google.auth.transport.grpc
238 import google.auth.transport.requests
239
240 http_request = google.auth.transport.requests.Request()
241
242 channel = google.auth.transport.grpc.secure_authorized_channel(
Jon Wayne Parrott840b3ac2016-11-10 12:07:51 -0800243 credentials, http_request, 'pubsub.googleapis.com:443')
Jon Wayne Parrott53c7b172016-11-10 10:44:30 -0800244
245.. note:: Even though gRPC is its own transport, you still need to use one of
246 the other HTTP transports with gRPC. The reason is that most credential
247 types need to make HTTP requests in order to refresh their access token.
248 The sample above uses the Requests transport, but any HTTP transport can
249 be used. Additionally, if you know that your credentials do not need to
250 make HTTP requests in order to refresh (as is the case with
251 :class:`jwt.Credentials`) then you can specify ``None``.
252
253Alternatively, you can create the channel yourself and use
254:class:`google.auth.transport.grpc.AuthMetadataPlugin`::
255
256 import grpc
257
258 metadata_plugin = AuthMetadataPlugin(credentials, http_request)
259
260 # Create a set of grpc.CallCredentials using the metadata plugin.
261 google_auth_credentials = grpc.metadata_call_credentials(
262 metadata_plugin)
263
264 # Create SSL channel credentials.
265 ssl_credentials = grpc.ssl_channel_credentials()
266
267 # Combine the ssl credentials and the authorization credentials.
268 composite_credentials = grpc.composite_channel_credentials(
269 ssl_credentials, google_auth_credentials)
270
271 channel = grpc.secure_channel(
272 'pubsub.googleapis.com:443', composite_credentials)
273
274You can use this channel to make a gRPC stub that makes authenticated requests
275to a gRPC service::
276
277 from google.pubsub.v1 import pubsub_pb2
278
279 pubsub = pubsub_pb2.PublisherStub(channel)
280
281 response = pubsub.ListTopics(
282 pubsub_pb2.ListTopicsRequest(project='your-project'))
283
284
285.. _gRPC: http://www.grpc.io/
286.. _Protocol Buffers:
287 https://developers.google.com/protocol-buffers/docs/overview
288.. _HTTP 2.0:
289 http://www.grpc.io/docs/guides/wire.html
290.. _Call Credentials:
291 http://www.grpc.io/docs/guides/auth.html