From fc7ff9fe8288b07442ae9c9a501190d935c1a5d7 Mon Sep 17 00:00:00 2001 From: Jason Gunthorpe Date: Wed, 5 Feb 2020 10:52:23 -0400 Subject: Update documentation For Gmail and other notes about O365 Signed-off-by: Jason Gunthorpe --- README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 59 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 2390056..5e1521f 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,11 @@ concurrently. Although it will function, it has not been optimized for giant email boxes and may not perform well. -Currently it operates only in an 'online mode' where the daemon must be +For safety it operates only in an 'online mode' where the daemon must be running. Any local changes made to the mailboxes when the daemon is stopped -are discarded. +are discarded. A '--offline' flag will keep changes to flags in the local +mailbox (but ignores removed maildir files). This is relatively safe but could +potentially loose flag changes done on the cloud side. # Microsoft Office365 Cloud Mailbox @@ -48,6 +50,21 @@ flag which causes the server to provide long term stable IDs for the same message. This avoids more cases where the messages have to be re-downloaded to again match them to local messages. +# Gmail Cloud Mailbox + +While Gmail has fairly good IMAP support, and does support OAUTH2 to IMAP, the +REST interface is a bit more scalable and robust. + +CMS uses the [Gmail API](https://developers.google.com/gmail/api/guides) to +access the mailbox. It can be pointed at any Label in GMail and uses this +history scheme to optimize updates. + +There is no support for push notifications as the Gmail API only considers +using notification in server/server configurations, not server/client. + +The IMAP 'Replied' flag is not supported. The Gmail API does not seem to +expose this feature. + # Configuration A small configuration file, written in Python, is used to setup the mailboxes @@ -61,6 +78,13 @@ MailDir("~/mail/INBOX") Office365("inbox", Office365_Account(user="user@domain.com")) ``` +or with Gmail: + +```Python +MailDir("~/mail/INBOX") +GMail("INBOX", GMail_Account(user="user@domain.com")) +``` + ## Run from git CMS requires a fair number of Python modules from PyPI that are not commonly @@ -72,18 +96,21 @@ with pip and then run the program from within it. # OAUTH2 Authentication Most cloud providers are now using OAUTH2, and often also provide options to -disable simple password authentication. This is done in the name of security -as OAUTH is the standards based way to support various MFA schemes. However, -OAUTH requires an interactive Web Browser to authenticate. This is challanging -for a Linux environment. - -CMS implements this in what has become the common way for a command line -application. It provides an internal web server which interacts with the -browser to perform the OAUTH protocol. When interactive authentication is -required it automatically launches a browser window to handle it. As a public -application CMS uses the new OAUTH 2.0 Proof Key for Code Exchange (PKCE) -protocol with the Authorization Code Grant to avoid needing 'client secrets' -or special service configuration. +disable simple password authentication. Both Microsoft and Google have +announced effective 'end of life' dates for password only 'basic +authentication'. This is done in the name of security as OAUTH is the +standards based way to support various MFA schemes. However, OAUTH requires an +interactive Web Browser to authenticate. This is challanging for a Linux +environment. + +CMS implements this following [RFC 8252](https://tools.ietf.org/html/rfc8252) +which has become the common way for a command line application to operate. It +provides an internal web server which interacts with the browser to perform +the OAUTH protocol. When interactive authentication is required it +automatically launches a browser window to handle it. As a public application +CMS uses the new OAUTH 2.0 Proof Key for Code Exchange (PKCE) protocol with +the Authorization Code Grant to and does not need to keep secret information +to be secure. The first time a user does this authentication they will be prompted to permit the 'cloud-maildir-sync' application to access their mailbox, in the normal @@ -115,6 +142,24 @@ avaiable. The Python [keyring](https://pypi.org/project/keyring/) module is used to store the encryption secret for OAUTH token storage. For Linux desktop appications this will automatically use gnome-keyring. +## OAUTH client_id's + +OAUTH requires every client to register with the authentication server and get +a client_id for operation. The authorization server operator can excert quite +a lot of control over the process of granting a client_id. For instance Google +requires quite a long review process before they will grant a fully operational +client_id. + +CMS comes included with default client_id's for GMail and Office365. However, +these IDs are hosted on various personal tenants, and have not necessarily +been made fully operational. While they are possibly good enough to get +started with this program, it is possible they will vanish some day, or hit +thier usage caps. + +One might consult other, [more +popular](https://hg.mozilla.org/comm-central/diff/3f1827133f9d4d20979ba0c11b34005a27461194/mailnews/base/util/OAuth2Providers.jsm), +open source projects for OAuth client_ids. + # General Operation CMS takes the approach that the cloud is the authoritative representation of @@ -176,9 +221,6 @@ set maildir_trash = yes Currently push notifications only work for a single mailbox as there is no way to determine which mailbox the notification was for unless the incremental JSON generated by the long-lived connection is parsed. -- Support gmail. While gmail has a much better IMAP server than Offce365, it - is fairly straight forward to implement its version of a REST protocol to - give basically the same capability set. - Provide some web-app on 'http://localhost:8080/'. CMS launches a web browser using the Python webbrowser module to open a browser window on the URL, however this is only functional for desktop cases. Ideally just having a -- cgit v1.2.3