branch: externals/auth-source-xoauth2-plugin
commit 1162d667e83ad726e65d2685af76dbeea546b465
Author: Xiyue Deng <manp...@gmail.com>
Commit: Xiyue Deng <manp...@gmail.com>
Add README.org with an introduction and usages
---
README.org | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 88 insertions(+)
diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..d233c06162
--- /dev/null
+++ b/README.org
@@ -0,0 +1,88 @@
+* Introduction
+
+This package provides a global minor mode for enabling support for
+xoauth2 authentication with auth-source. OAuth 2.0, which stands for
+“Open Authorization”, is a standard designed to allow a website or
+application to access resources hosted by other web apps on behalf of
+a user. The OAuth 2.0 Authorization Protocol Extensions (xoauth2)
+extend the OAuth 2.0 Authentication Protocol and the JSON Web Token
+(JWT) to enable server-to-server authentication. More info please
+check out [[https://stackoverflow.com/a/76389679/2337550][this stackoverflow
answer]].
+
+* Setup
+
+To set up, please put this file in the `load-path' of Emacs, and add
+the following lines in your Emacs configuration:
+
+#+BEGIN_SRC emacs-lisp
+ (require 'auth-source-xoauth2-plugin)
+ (auth-source-xoauth2-plugin-mode t)
+#+END_SRC
+
+or with use-package:
+
+#+BEGIN_SRC emacs-lisp
+ (use-package auth-source-xoauth2-plugin
+ :custom
+ (auth-source-xoauth2-plugin-mode t))
+#+END_SRC
+
+After enabling, smtpmail should be supported. To enable this in Gnus
+nnimap, you should also set `(nnimap-authenticator xoauth2)' in the
+corresponding account settings in `gnus-secondary-select-methods' as
+the following:
+
+#+BEGIN_SRC emacs-lisp
+ (nnimap "account_name"
+ ...
+ (nnimap-authenticator xoauth2))
+#+END_SRC
+
+To disable, just toggle the minor mode off by calling `M-x
+auth-source-xoauth2-plugin-mode' again.
+
+auth-source uses the `secret' field in auth-source file as password
+for authentication, including xoauth2. To decide which
+authentication method to use (e.g. plain password vs xoauth2), it
+inspects the `auth' field from the auth-source entry, and if the
+value is `xoauth2', it will try to gather data and get the access
+token for use of xoauth2 authentication; otherwise, it will fallback
+to the default authentication method.
+
+When xoauth2 authentication is enabled, it will try to get the
+following data from the auth-source entry: `auth-url', `token-url',
+`scope', `client-id', `client-secret', `redirect-uri', and optionally
+`state'. An example Authinfo entry (in JSON format as
+~/.authinfo.json.gpg) for an Gmail account may look like below:
+
+#+BEGIN_SRC json
+ {
+ "machine": "<your_imap_address_or_email>",
+ "login": "<your_email>",
+ "port": "imaps",
+ "auth": "xoauth2",
+ "auth-url": "https://accounts.google.com/o/oauth2/auth";,
+ "token-url": "https://accounts.google.com/o/oauth2/token";,
+ "client-id": "<the_client_id_from_your_app>",
+ "client-secret": "<the_client_secret_from_your_app>",
+ "redirect-uri": "https://oauth2.dance/";,
+ "scope": "https://mail.google.com";
+ }
+#+END_SRC
+
+These information will be used by oauth2 to retrieve the access-token.
+This package uses an advice to switch the auth-source search result
+from the `password' to the `access-token' it got, which in turn will
+be used to construct the xoauth2 authentication string, currently in
+nnimap-login and smtpmail-try-auth-method. To really enable xoauth2
+in smtpmail, it will add 'xoauth2 to 'smtpmail-auth-supported (if it
+is not already in the list) using `add-to-list' so that xoauth2 is
+tried first.
+
+** Notes
+
+Currently the auth-source requires the searched entry must have
+`secret' field set in the entry, which is not necessary when using
+xoauth2. Therefore in the advice it temporarily disables checking
+for `:secret' if set and perform the search, and check the result
+before returning.
