1# OAuth 2.0
2
3This document describes OAuth 2.0, when to use it, how to acquire client IDs, and how to use it with the Google APIs Client Library for Python.
4
5## OAuth 2.0 explained
6
7OAuth 2.0 is the authorization protocol used by Google APIs. It is summarized on the [Authentication](auth.md) page of this library's documentation, and there are other good references as well:
8
9*   [The OAuth 2.0 Authorization Protocol](https://tools.ietf.org/html/rfc6749)
10*   [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/accounts/docs/OAuth2)
11
12The protocol is solving a complex problem, so it can be difficult to understand. This presentation explains the important concepts of the protocol, and introduces you to how the library is used at each step.
13
14## Acquiring client IDs and secrets
15
16You can get client IDs and secrets on the [API Access pane](https://console.developers.google.com/apis/credentials) of the Google APIs Console. There are different types of client IDs, so be sure to get the correct type for your application:
17
18*   Web application client IDs
19*   Installed application client IDs
20*   [Service Account](https://developers.google.com/accounts/docs/OAuth2ServiceAccount) client IDs
21
22**Warning**: Keep your client secret private. If someone obtains your client secret, they could use it to consume your quota, incur charges against your Google APIs Console project, and request access to user data.
23
24## The `google-auth` and `google-auth-oauthlib` libraries
25
26The [google-auth-oauthlib](https://google-auth-oauthlib.readthedocs.io/en/latest/reference/modules.html) library should be used for handling OAuth 2.0 protocol steps required for making API calls. You should install [google-auth](https://pypi.org/project/google-auth) and [google-auth-oauthlib](https://pypi.org/project/google-auth-oauthlib). The sections below describe important modules, classes, and functions of `google-auth-oauthlib` library.
27
28## Flows
29
30The purpose of a `Flow` class is to acquire credentials that authorize your application access to user data. In order for a user to grant access, OAuth 2.0 steps require your application to potentially redirect their browser multiple times. A `Flow` object has functions that help your application take these steps and acquire credentials. `Flow` objects are only temporary and can be discarded once they have produced credentials, but they can also be [pickled](http://docs.python.org/library/pickle.html) and stored. This section describes the various methods to create and use `Flow` objects.
31
32### Installed App Flow
33
34The [google_auth_oauthlib.flow.InstalledAppFlow](https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow) class is used for installed applications. This flow is useful for local development or applications that are installed on a desktop operating system. See [OAuth 2.0 for Installed Applications](oauth-installed.md).
35
36```python
37from google_auth_oauthlib.flow import InstalledAppFlow
38
39flow = InstalledAppFlow.from_client_secrets_file(
40    'client_secrets.json',
41    scopes=['profile', 'email'])
42
43flow.run_local_server()
44```
45
46### Flow
47
48The example below uses the `Flow` class to handle the installed application authorization flow.
49
50#### from_client_secrets_file()
51
52The [google_auth_oauthlib.Flow.from_client_secrets()](https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.Flow.from_client_secrets_file) method creates a `Flow` object from a [client_secrets.json](client-secrets.md) file. This [JSON](http://www.json.org/) formatted file stores your client ID, client secret, and other OAuth 2.0 parameters.
53
54The following shows how you can use `from_client_secrets_file()` to create a `Flow` object:
55
56```python
57from google_auth_oauthlib.flow import Flow
58...
59flow = Flow.from_client_secrets_file(
60    'path/to/client_secrets.json',
61    scopes=['openid', 'https://www.googleapis.com/auth/userinfo.email', 'https://www.googleapis.com/auth/userinfo.profile'],
62    redirect_uri='urn:ietf:wg:oauth:2.0:oob')
63```
64
65#### authorization_url()
66
67The [authorization_url()](https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.authorization_url) function of the `Flow` class is used to generate the authorization server URI. Once you have the authorization server URI, redirect the user to it. The following is an example call to this function:
68
69```python
70auth_uri = flow.authorization_url()
71# Redirect the user to auth_uri on your platform.
72```
73
74If the user has previously granted your application access, the authorization server immediately redirects again to `redirect_uri`. If the user has not yet granted access, the authorization server asks them to grant your application access. If they grant access, they get redirected to `redirect_uri` with a `code` query string parameter similar to the following:
75
76`http://example.com/auth_return/?code=kACAH-1Ng1MImB...AA7acjdY9pTD9M`
77
78If they deny access, they get redirected to `redirect_uri` with an `error` query string parameter similar to the following:
79
80`http://example.com/auth_return/?error=access_denied`
81
82#### fetch_token()
83
84The [fetch_token()](https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.fetch_token) function of the `Flow` class exchanges an authorization code for a `Credentials` object. The credentials will be available in `flow.credentials`.
85
86```python
87# The user will get an authorization code. This code is used to get the
88# access token.
89code = input('Enter the authorization code: ')
90flow.fetch_token(code=code)
91```
92
93
94## Credentials
95
96A `Credentials` object holds refresh and access tokens that authorize access to a single user's data. These objects are applied to `httplib2.Http` objects to authorize access. They only need to be applied once and can be stored. This section describes the various methods to create and use `Credentials` objects.
97
98**Note**: Credentials can be automatically detected in Google App Engine and Google Compute Engine. See [Using OAuth 2.0 for Server to Server Applications](oauth-server.md#examples).
99
100### User Credentials
101
102The [google.oauth2.credentials.Credentials](https://google-auth.readthedocs.io/en/latest/reference/google.oauth2.credentials.html#google.oauth2.credentials.Credentials) class holds OAuth 2.0 credentials that authorize access to a user's data. A `Flow` object can create one for you.
103
104### Service Account Credentials
105
106The [google.oauth2.service_account.Credentials](https://google-auth.readthedocs.io/en/latest/reference/google.oauth2.service_account.html#google.oauth2.service_account.Credentials) class is only used with [OAuth 2.0 Service Accounts](https://developers.google.com/accounts/docs/OAuth2ServiceAccount). No end-user is involved for these server-to-server API calls, so you can create this object directly.
107
108```python
109from google.oauth2 import service_account
110
111credentials = service_account.Credentials.from_service_account_file(
112    '/path/to/key.json')
113
114scoped_credentials = credentials.with_scopes(
115    ['https://www.googleapis.com/auth/cloud-platform'])
116```
117
118### Using Credentials
119
120Once a valid credentials object has been obtained it is passed to the build function:
121
122```python
123from google_auth_oauthlib.flow import InstalledAppFlow
124from googleapiclient.discovery import build
125
126flow = InstalledAppFlow.from_client_secrets_file(
127    'client_secrets.json',
128    scopes=['openid', 'https://www.googleapis.com/auth/userinfo.email', 'https://www.googleapis.com/auth/userinfo.profile'])
129
130flow.run_local_server()
131credentials = flow.credentials
132
133service = build('calendar', 'v3', credentials=credentials)
134
135# Optionally, view the email address of the authenticated user.
136user_info_service = build('oauth2', 'v2', credentials=credentials)
137user_info = user_info_service.userinfo().get().execute()
138print(user_info['email'])
139
140```
141
142## Storage
143
144`google-auth-oauthlib` does not currently have support for credentials storage. It may be added in the future. See [oauth2client deprecation](https://google-auth.readthedocs.io/en/latest/oauth2client-deprecation.html#replacement) for more details.
145
146## oauth2client deprecation
147The [oauth2client](http://oauth2client.readthedocs.org/en/latest/index.html) library was previously recommended for handling the OAuth 2.0 protocol. It is now deprecated, and we recommend `google-auth` and `google-auth-oauthlib`. See [oauth2client deprecation](https://google-auth.readthedocs.io/en/latest/oauth2client-deprecation.html) for more details.
148