learn XOAUTH2 authentication

Signed-off-by: François Lamboley <francois.lamboley@happn.com>
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>

offlineimap.conf

@@ -673,9 +673,42 @@ remoteuser = username
 # limitations, if GSSAPI is set, it will be tried first, no matter where it was
 # specified in the list.
 #
-#auth_mechanisms = GSSAPI, CRAM-MD5, PLAIN, LOGIN
+#auth_mechanisms = GSSAPI, CRAM-MD5, XOAUTH2, PLAIN, LOGIN
 
 
+# This option stands in the [Repository RemoteExample] section.
+#
+# XOAuth2 authentication (for instance, to use with Gmail).
+#
+# This feature is currently EXPERIMENTAL (tested on Gmail only, but should work
+# with type = IMAP for compatible servers).
+#
+# Mandatory parameters are "oauth2_client_id", "oauth2_client_secret" and
+# "oauth2_refresh_token". See below to learn how to get those.
+#
+# Specify the OAuth2 client id and secret to use for the connection..
+# Here's how to register an OAuth2 client for Gmail, as of 10-2-2016:
+#    - Go to the Google developer console
+#         https://console.developers.google.com/project
+#    - Create a new project
+#    - In API & Auth, select Credentials
+#    - Setup the OAuth Consent Screen
+#    - Then add Credentials of type OAuth 2.0 Client ID
+#    - Choose application type Other; type in a name for your client
+#    - You now have a client ID and client secret
+#
+#oauth2_client_id = YOUR_CLIENT_ID
+#oauth2_client_secret = YOUR_CLIENT_SECRET
+
+# Specify the refresh token to use for the connection to the mail server.
+# Here's an example of a way to get a refresh token:
+#    - Clone this project: https://github.com/google/gmail-oauth2-tools
+#    - Type the following command-line in a terminal and follow the instructions
+#         python python/oauth2.py --generate_oauth2_token \
+#            --client_id=YOUR_CLIENT_ID --client_secret=YOUR_CLIENT_SECRET
+#
+#oauth2_refresh_token = REFRESH_TOKEN
+
 ########## Passwords
 
 # There are six ways to specify the password for the IMAP server: