diff options
| -rw-r--r-- | contrib/caldav/README.md | 90 |
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#' +``` |