From: Kevin McCarthy <kevin@8t8.us>
Date: Wed, 7 Nov 2018 21:38:53 +0000 (-0800)
Subject: Add some brief documentation on OAUTH support.
X-Git-Tag: mutt-1-11-rel~15
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f8153009b35aef1959fdde23f649a7ae66a4ab19;p=mutt

Add some brief documentation on OAUTH support.

These are just pulled from Brandon's commit message.
---

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 98541db5..8a38ee8e 100644
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -8298,6 +8298,45 @@ most-secure to least-secure.
 
 </sect1>
 
+<sect1 id="oauth">
+<title>OAUTHBEARER Support</title>
+
+<para>
+Preliminary OAUTH support for IMAP, POP, and SMTP is provided via
+external scripts.
+</para>
+
+<para>
+At least for Gmail, you can use the <literal>oauth2.py</literal>
+script from Google's gmail-oauth2-tools: <ulink
+url="https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py"
+>https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py</ulink>
+</para>
+
+<para>
+You'll need to get your own oauth client credentials for Gmail here:
+<ulink url="https://console.developers.google.com/apis/credentials"
+>https://console.developers.google.com/apis/credentials</ulink>
+</para>
+
+<para>
+Then, you'd use <literal>oauth2.py</literal> with
+<literal>--generate_oauth2_token</literal> to get a refresh token, and
+configure mutt with:
+</para>
+
+<screen>
+set imap_authenticators="oauthbearer"
+set imap_oauth_refresh_command="/path/to/oauth2.py --quiet --user=[email_address]\
+    --client_id=[client_id] --client_secret=[client_secret]\
+    --refresh_token=[refresh_token]"
+</screen>
+
+<para>
+Substitute pop or smtp for imap in the above example to configure for those.
+</para>
+</sect1>
+
 <sect1 id="account-hook">
 <title>Managing Multiple Accounts</title>
 
diff --git a/init.h b/init.h
index 021214df..eafce344 100644
--- a/init.h
+++ b/init.h
@@ -1338,7 +1338,7 @@ struct option_t MuttVars[] = {
   ** The command to run to generate an OAUTH refresh token for
   ** authorizing your connection to your IMAP server.  This command will be
   ** run on every connection attempt that uses the OAUTHBEARER authentication
-  ** mechanism.
+  ** mechanism.  See ``$oauth'' for details.
   */
   { "imap_pass", 	DT_STR,  R_NONE, UL &ImapPass, UL 0 },
   /*
@@ -2424,7 +2424,7 @@ struct option_t MuttVars[] = {
   ** The command to run to generate an OAUTH refresh token for
   ** authorizing your connection to your POP server.  This command will be
   ** run on every connection attempt that uses the OAUTHBEARER authentication
-  ** mechanism.
+  ** mechanism.  See ``$oauth'' for details.
   */
   { "pop_pass",		DT_STR,	 R_NONE, UL &PopPass, UL "" },
   /*
@@ -3402,7 +3402,7 @@ struct option_t MuttVars[] = {
   ** The command to run to generate an OAUTH refresh token for
   ** authorizing your connection to your SMTP server.  This command will be
   ** run on every connection attempt that uses the OAUTHBEARER authentication
-  ** mechanism.
+  ** mechanism.  See ``$oauth'' for details.
   */
   { "smtp_pass", 	DT_STR,  R_NONE, UL &SmtpPass, UL 0 },
   /*