Update calcurse-caldav documentation for OAuth2

Append instructions and information on synchronization with OAuth2-based
services, specifically Google Calendar.

Signed-off-by: Randy Ramos <rramos1295@gmail.com>
Signed-off-by: Lukas Fleischer <lfleischer@calcurse.org>

1 files changed, 90 insertions, 0 deletions

diff --git a/contrib/caldav/README.md b/contrib/caldav/README.md
index c35813d..63f6f20 100644
--- a/contrib/caldav/README.md
+++ b/contrib/caldav/README.md
@@ -65,3 +65,93 @@ added or deleted. It then
 Note: Since calcurse does not use unique identifiers for items, it cannot keep
 track of moved/edited items. Thus, modifying an item is equivalent to deleting
 the old item and creating a new one.
+
+OAuth2 Authentication
+---------------------
+
+calcurse-caldav also has support for services requiring OAuth2 authentication
+such as Google Calendar. Note that you can only have a single calendar synced
+at any given time, regardless of authentication method. To enable OAuth2 you
+will need to:
+
+* Change *AuthMethod* from "*basic*" to "*oauth2*" in your config file
+* Fill in the appropriate settings in your config file: "*ClientID*",
+ "*ClientSecret*", "*Scope*", and "*RedirectURI*". These can be obtained from
+ the API provider. (See below for Google Calendar)
+* Install *oauth2client* for Python 3 using *pip* (e.g. `pip3 install --user
+oauth2client`) or your distribution's package manager
+
+Synchronization With Google Calendar
+-------------------------------------
+
+You will need to use your Google account to create a Google API project and
+enable both the CalDAV API and the Google Calendar API. We will be doing this to
+receive a Client ID and Client Secret. The hostname, path, scope and redirect
+URI are listed below.
+
+First, you will need to go to the [Google Developers Console](https://console.developers.google.com/project) and click *Create
+Project*. After doing that, you can go to the [API Library](https://console.developers.google.com/project/_/apiui/apis/library) and
+search for the CalDAV API and enable it for your project. You will then need to
+do the same for the Google Calendar API.
+
+Next, go to the [Credentials page](https://console.developers.google.com/project/_/apiui/credential)
+, click on *Create credentials*, and choose *OAuth client ID*. If it asks you
+to "set a product name on the consent screen", click on *Configure consent
+screen* to do so. Any product name will do. Upon saving and returning to the
+"Create client ID" screen, choose *Other* as the Application type and click
+*Create*. You now have your Client ID and Client Secret to put into your
+calcurse-caldav config file!
+
+The following options should also be changed in your config file:
+
+```
+Hostname = apidata.googleusercontent.com
+Path = /caldav/v2/*your_calendar_id_here*/events/
+Scope = https://www.googleapis.com/auth/calendar
+```
+
+Your Calendar ID for "*Path*" should be your email for the default calendar.
+If you have multiple calendars, you can get the Calendar ID by going under
+Calendar Details at [calendar.google.com](https://calendar.google.com).
+The default Redirect URI in the config file is http://127.0.0.1; this should
+work fine, but can be changed to http://localhost, a local web server, or
+another device if you encounter errors related to it.
+
+A complete config file for example@gmail.com would have the following options:
+
+```
+[General]
+
+...
+
+Hostname = apidata.googleusercontent.com
+Path = /caldav/v2/example@gmail.com/events/
+AuthMethod = oauth2
+
+...
+
+[OAuth2]
+ClientID = 22802342jlkjlksjdlfkjq1htpvbcn.apps.googleusercontent.com
+ClientSecret = XPYGqHFsfF343GwJeOGiUi
+Scope = https://www.googleapis.com/auth/calendar
+RedirectURI = http://127.0.0.1
+```
+
+[The full guide from Google can be found here.](https://developers.google.com/google-apps/calendar/caldav/v2/guide)
+
+Upon your first run with the `--init` flag, you will be asked to go to a URL to
+log in and authorize synchronization with your Google account. You can access
+this URL on any other device if you cannot open a browser locally (e.g., on
+a headless server). Once you authorize synchronization, you will be redirected
+to your Redirect URI with a code attached to the end, e.g.,
+`http://127.0.0.1/?code=4/Ok6mBNW2nppfIwyL-Q1ZPVkEk3zZdZN3mHcY#`. You will need
+to copy the code after `http://12.0.0.1?code=`. In this case, it would be
+`4/Ok6mBNW2nppfIwyL-Q1ZPVkEk3zZdZN3mHcY#`.
+
+Finally pass this authorization code to calcurse-caldav with the `--authcode`
+flag and initialize the synchronization database like so (note that the quotes
+around the authorization code might be necessary or not, depending on your shell):
+
+```
+calcurse-caldav --init keep-remote --authcode '4/Ok6mBNW2nppfIwyL-Q1ZPVkEk3zZdZN3mHcY#'
+```