1OAuth made easy
2===============
3
4Authentication in two lines
5---------------------------
6
7OAuth2.0 is complex and difficult to start with. To make it more simple,
8*PyDrive* makes all authentication into just two lines.
9
10.. code-block:: python
11
12    from pydrive.auth import GoogleAuth
13
14    gauth = GoogleAuth()
15    # Create local webserver and auto handles authentication.
16    gauth.LocalWebserverAuth()
17
18    # Or use the CommandLineAuth(), which provides you with a link to paste
19    # into your browser. The site it leads to then provides you with an
20    # authentication token which you paste into the command line.
21    # Commented out as it is an alternative to the LocalWebserverAuth() above,
22    # and someone will just copy-paste the entire thing into their editor.
23
24    # gauth.CommandLineAuth()
25
26To make this code work, you need to download the application configurations file
27from APIs Console. Take a look at quickstart_ for detailed instructions.
28
29`LocalWebserverAuth()`_ is a built-in method of `GoogleAuth`_ which sets up
30local webserver to automatically receive authentication code from user and
31authorizes by itself. You can also use `CommandLineAuth()`_ which manually
32takes code from user at command line.
33
34.. _quickstart: ./quickstart.html#authentication
35.. _`LocalWebserverAuth()`: ./pydrive.html#pydrive.auth.GoogleAuth.LocalWebserverAuth
36.. _`GoogleAuth`: ./pydrive.html#pydrive.auth.GoogleAuth
37.. _`CommandLineAuth()`: ./pydrive.html#pydrive.auth.GoogleAuth.CommandLineAuth
38
39Automatic and custom authentication with *settings.yaml*
40--------------------------------------------------------
41
42Read this section if you need a custom authentication flow, **such as silent
43authentication on a remote machine**. For an example of such a setup have a look
44at `Sample settings.yaml`_.
45
46OAuth is complicated and it requires a lot of settings. By default,
47when you don't provide any settings, *PyDrive* will automatically set default
48values which works for most of the cases. Here are some default settings.
49
50- Read client configuration from file *client_secrets.json*
51- OAuth scope: :code:`https://www.googleapis.com/auth/drive`
52- Don't save credentials
53- Don't retrieve refresh token
54
55However, you might want to customize these settings while maintaining two lines
56of clean code. If that is the case, you can make *settings.yaml* file in your
57working directory and *PyDrive* will read it to customize authentication
58behavior.
59
60These are all the possible fields of a *settings.yaml* file:
61
62.. code-block:: python
63
64    client_config_backend: {{str}}
65    client_config_file: {{str}}
66    client_config:
67      client_id: {{str}}
68      client_secret: {{str}}
69      auth_uri: {{str}}
70      token_uri: {{str}}
71      redirect_uri: {{str}}
72      revoke_uri: {{str}}
73
74    save_credentials: {{bool}}
75    save_credentials_backend: {{str}}
76    save_credentials_file: {{str}}
77
78    get_refresh_token: {{bool}}
79
80    oauth_scope: {{list of str}}
81
82Fields explained:
83
84:client_config_backend (str): From where to read client configuration(API application settings such as client_id and client_secrets) from. Valid values are 'file' and 'settings'. **Default**: 'file'. **Required**: No.
85:client_config_file (str): When *client_config_backend* is 'file', path to the file containing client configuration. **Default**: 'client_secrets.json'. **Required**: No.
86:client_config (dict): Place holding dictionary for client configuration when *client_config_backend* is 'settings'. **Required**: Yes, only if *client_config_backend* is 'settings'
87:client_config['client_id'] (str): Client ID of the application. **Required**: Yes, only if *client_config_backend* is 'settings'
88:client_config['client_secret'] (str): Client secret of the application. **Required**: Yes, only if *client_config_backend* is 'settings'
89:client_config['auth_uri'] (str): The authorization server endpoint URI. **Default**: 'https://accounts.google.com/o/oauth2/auth'. **Required**: No.
90:client_config['token_uri'] (str): The token server endpoint URI. **Default**: 'https://accounts.google.com/o/oauth2/token'. **Required**: No.
91:client_config['redirect_uri'] (str): Redirection endpoint URI. **Default**: 'urn:ietf:wg:oauth:2.0:oob'. **Required**: No.
92:client_config['revoke_uri'] (str): Revoke endpoint URI. **Default**: None. **Required**: No.
93:save_credentials (bool): True if you want to save credentials. **Default**: False. **Required**: No.
94:save_credentials_backend (str): Backend to save credentials to. 'file' is the only valid value for now. **Default**: 'file'. **Required**: No.
95:save_credentials_file (str): Destination of credentials file. **Required**: Yes, only if *save_credentials_backend* is 'file'.
96:get_refresh_token (bool): True if you want to retrieve refresh token along with access token. **Default**: False. **Required**: No.
97:oauth_scope (list of str): OAuth scope to authenticate. **Default**: ['https://www.googleapis.com/auth/drive']. **Required**: No.
98
99Sample *settings.yaml*
100______________________
101
102::
103
104    client_config_backend: settings
105    client_config:
106      client_id: 9637341109347.apps.googleusercontent.com
107      client_secret: psDskOoWr1P602PXRTHi
108
109    save_credentials: True
110    save_credentials_backend: file
111    save_credentials_file: credentials.json
112
113    get_refresh_token: True
114
115    oauth_scope:
116      - https://www.googleapis.com/auth/drive.file
117      - https://www.googleapis.com/auth/drive.install
118
119Building your own authentication flow
120-------------------------------------
121
122You might want to build your own authentication flow. For example, you might
123want to integrate your existing website with Drive API. In that case, you can
124customize authentication flow as follwing:
125
1261. Get authentication Url from `GetAuthUrl()`_.
1272. Ask users to visit the authentication Url and grant access to your application. Retrieve authentication code manually by user or automatically by building your own oauth2callback.
1283. Call `Auth(code)`_ with the authentication code you retrieved from step 2.
129
130Your *settings.yaml* will work for your customized authentication flow, too.
131
132Here is a sample code for your customized authentication flow
133
134.. code-block:: python
135
136    from pydrive.auth import GoogleAuth
137
138    gauth = GoogleAuth()
139    auth_url = gauth.GetAuthUrl() # Create authentication url user needs to visit
140    code = AskUserToVisitLinkAndGiveCode(auth_url) # Your customized authentication flow
141    gauth.Auth(code) # Authorize and build service from the code
142
143.. _`GetAuthUrl()`: ./pydrive.html#pydrive.auth.GoogleAuth.GetAuthUrl
144.. _`Auth(code)`: ./pydrive.html#pydrive.auth.GoogleAuth.Auth
145