Remove oauth2client from docs (#738)
* Use google-auth and google-auth-oauthlib in oauth2 docs.
* Remove basic server sample
diff --git a/docs/oauth.md b/docs/oauth.md
index 71874c9..2ce18e1 100644
--- a/docs/oauth.md
+++ b/docs/oauth.md
@@ -21,49 +21,53 @@
**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.
-## The oauth2client library
+## The `google-auth` and `google-auth-oauthlib` libraries
-The [oauth2client](http://oauth2client.readthedocs.org/en/latest/index.html) library is included with the Google APIs Client Library for Python. It handles all steps of the OAuth 2.0 protocol required for making API calls. It is available as a separate [package](https://pypi.python.org/pypi/oauth2client) if you only need an OAuth 2.0 library. The sections below describe important modules, classes, and functions of this library.
+The [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.
## Flows
The 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.
-**Note**: See the [Using Google App Engine](app-engine.md) and [Using Django](django.md) pages for platform-specific Flows.
+### Installed App Flow
-### flow_from_clientsecrets()
+The [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).
-The [oauth2client.client.flow_from_clientsecrets()](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.client.html#oauth2client.client.flow_from_clientsecrets) 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.
+```python
+from google_auth_oauthlib.flow import InstalledAppFlow
-The following shows how you can use `flow_from_clientsecrets()` to create a `Flow` object:
+flow = InstalledAppFlow.from_client_secrets_file(
+ 'client_secrets.json',
+ scopes=['profile', 'email'])
-```py
-from oauth2client.client import flow_from_clientsecrets
-...
-flow = flow_from_clientsecrets('path_to_directory/client_secrets.json',
- scope='https://www.googleapis.com/auth/calendar',
- redirect_uri='http://example.com/auth_return')
-```
-
-### OAuth2WebServerFlow
-
-Despite its name, the [oauth2client.client.OAuth2WebServerFlow](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.client.html#oauth2client.client.OAuth2WebServerFlow) class is used for both installed and web applications. It is created by passing the client ID, client secret, and scope to its constructor: You provide the constructor with a `redirect_uri` parameter. This must be a URI handled by your application.
-
-```py
-from oauth2client.client import OAuth2WebServerFlow
-...
-flow = OAuth2WebServerFlow(client_id='your_client_id',
- client_secret='your_client_secret',
- scope='https://www.googleapis.com/auth/calendar',
- redirect_uri='http://example.com/auth_return')
+flow.run_local_server()
```
-### step1_get_authorize_url()
+### Flow
-The [step1_get_authorize_url()](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.client.html#oauth2client.client.OAuth2WebServerFlow.step1_get_authorize_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:
+The example below uses the `Flow` class to handle the installed appplication authorization flow.
-```py
-auth_uri = flow.step1_get_authorize_url()
+#### from_client_secrets_file()
+
+The [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.
+
+The following shows how you can use `from_client_secrets_file()` to create a `Flow` object:
+
+```python
+from google_auth_oauthlib.flow import Flow
+...
+flow = Flow.from_client_secrets_file(
+ 'path/to/client_secrets.json',
+ scopes=['profile', 'email'],
+ redirect_uri='urn:ietf:wg:oauth:2.0:oob')
+```
+
+#### authorization_url()
+
+The [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:
+
+```python
+auth_uri = flow.authorization_url()
# Redirect the user to auth_uri on your platform.
```
@@ -75,106 +79,63 @@
`http://example.com/auth_return/?error=access_denied`
-### step2_exchange()
+#### fetch_token()
-The [step2_exchange()](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.client.html#oauth2client.client.OAuth2WebServerFlow.step2_exchange) function of the `Flow` class exchanges an authorization code for a `Credentials` object. Pass the `code` provided by the authorization server redirection to this function:
+The [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`.
-```py
-credentials = flow.step2_exchange(code)
+```python
+# The user will get an authorization code. This code is used to get the
+# access token.
+code = input('Enter the authorization code: ')
+flow.fetch_token(code=code)
```
+
## Credentials
A `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.
-**Note**: See the [Using Google App Engine](google-app-engine.md) and [Using Django](django.md) pages for platform-specific Credentials.
+**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).
-### OAuth2Credentials
+### User Credentials
-The [oauth2client.client.OAuth2Credentials](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.client.html#oauth2client.client.OAuth2Credentials) class holds OAuth 2.0 credentials that authorize access to a user's data. Normally, you do not create this object by calling its constructor. A `Flow` object can create one for you.
+The [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.
-### ServiceAccountCredentials
+### Service Account Credentials
-The [oauth2client.service_account.ServiceAccountCredentials](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.service_account.html) 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 without using a `Flow` object.
+The [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.
-### AccessTokenCredentials
+```python
+from google.oauth2 import service_account
-The [oauth2client.client.AccessTokenCredentials](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.client.html#oauth2client.client.AccessTokenCredentials) class is used when you have already obtained an access token by some other means. You can create this object directly without using a `Flow` object.
+credentials = service_account.Credentials.from_service_account_file(
+ '/path/to/key.json')
-### authorize()
-
-Use the [authorize()](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.client.html#oauth2client.client.Credentials.authorize) function of the `Credentials` class to apply necessary credential headers to all requests made by an [httplib2.Http](http://bitworking.org/projects/httplib2/doc/html/libhttplib2.html#httplib2.Http) instance:
-
-```py
-import httplib2
-...
-http = httplib2.Http()
-http = credentials.authorize(http)
+scoped_credentials = credentials.with_scopes(
+ ['https://www.googleapis.com/auth/cloud-platform'])
```
-Once an `httplib2.Http` object has been authorized, it is typically passed to the build function:
+### Using Credentials
-```py
-from apiclient.discovery import build
-...
-service = build('calendar', 'v3', http=http)
+Once a valid credentials object has been obtained it is passed to the build function:
+
+```python
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+
+flow = InstalledAppFlow.from_client_secrets_file(
+ 'client_secrets.json',
+ scopes=['profile', 'email'])
+
+flow.run_local_server()
+credentials = flow.credentials
+
+service = build('calendar', 'v3', credentials=credentials)
```
## Storage
-A [oauth2client.client.Storage](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.client.html#oauth2client.client.Storage) object stores and retrieves `Credentials` objects. This section describes the various methods to create and use `Storage` objects.
+`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.
-**Note**: See the [Using Google App Engine](app-engine.md) and [Using Django](django.md) pages for platform-specific Storage.
-
-### file.Storage
-
-The [oauth2client.file.Storage](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.file.html#oauth2client.file.Storage) class stores and retrieves a single `Credentials` object. The class supports locking such that multiple processes and threads can operate on a single store. The following shows how to open a file, save `Credentials` to it, and retrieve those credentials:
-
-```py
-from oauth2client.file import Storage
-...
-storage = Storage('_a_credentials_file_')
-storage.put(credentials)
-...
-credentials = storage.get()
-```
-
-### multistore_file
-
-The [oauth2client.contrib.multistore_file](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.contrib.multistore_file.html) module allows multiple credentials to be stored. The credentials are keyed off of:
-
-* client ID
-* user agent
-* scope
-
-### keyring_storage
-
-The [oauth2client.contrib.keyring_storage](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.contrib.keyring_storage.html) module allows a single `Credentials` object to be stored in a [password manager](http://en.wikipedia.org/wiki/Password_manager) if one is available. The credentials are keyed off of:
-
-* Name of the client application
-* User name
-
-```py
-from oauth2client.contrib.keyring_storage import Storage
-...
-storage = Storage('_application name_', '_user name_')
-storage.put(credentials)
-...
-credentials = storage.get()
-```
-
-## Command-line tools
-
-The [oauth2client.tools.run_flow()](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.tools.html#oauth2client.tools.run_flow) function can be used by command-line applications to acquire credentials. It takes a `Flow` argument and attempts to open an authorization server page in the user's default web browser. The server asks the user to grant your application access to the user's data. If the user grants access, the run() function returns new credentials. The new credentials are also stored in the `Storage` argument, which updates the file associated with the `Storage` object.
-
-The [oauth2client.tools.run_flow()](http://oauth2client.readthedocs.org/en/latest/source/oauth2client.tools.html#oauth2client.tools.run_flow) function is controlled by command-line flags, and the Python standard library [argparse](http://docs.python.org/dev/library/argparse.html) module must be initialized at the start of your program. Argparse is included in Python 2.7+, and is available as a [separate package](https://pypi.python.org/pypi/argparse) for older versions. The following shows an example of how to use this function:
-
-```py
-import argparse
-from oauth2client import tools
-
-parser = argparse.ArgumentParser(parents=[tools.argparser])
-flags = parser.parse_args()
-...
-credentials = tools.run_flow(flow, storage, flags)
-```
+## oauth2client deprecation
+The [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.
\ No newline at end of file