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