Summary: authentication source plugin for xoauth2
Requires: emacs-28.1, oauth2-0.17
Website: https://elpa.gnu.org/packages/auth-source-xoauth2-plugin.html
Maintainer: Xiyue Deng <manp...@gmail.com>
Author: Xiyue Deng <manp...@gmail.com>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AUTH-SOURCE XOAUTH2 PLUGIN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2024-11-08
1 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 [this stackoverflow answer].
[this stackoverflow answer]
<https://stackoverflow.com/a/76389679/2337550>
2 Setup
═══════
To set up, please put this file in the `load-path' of Emacs, and add
the following lines in your Emacs configuration:
┌────
│ (require 'auth-source-xoauth2-plugin)
│ (auth-source-xoauth2-plugin-mode t)
└────
or with use-package:
┌────
│ (use-package auth-source-xoauth2-plugin
│ :custom
│ (auth-source-xoauth2-plugin-mode t))
└────
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:
┌────
│ (nnimap "account_name"
│ ...
│ (nnimap-authenticator xoauth2)
│ ...
│ )
└────
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 (you
need to fill in the data between `<' and `>' based on your account
settings):
┌────
│ {
│ "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";
│ }
└────
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.
2.1 Comparison with other xoauth2 implementations
─────────────────────────────────────────────────
[auth-source-xoauth2] <https://github.com/ccrusius/auth-source-xoauth2>
2.1.1 [auth-source-xoauth2]
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
This plugin takes inspirations from auth-source-xoauth2 to advice the
auth-source-search backends to add xoauth2 access-token for
authentication. The implementation is independent and reuses many
existing facilities in `auth-source.el', where auth-source-xoauth2
reimplemented most of the required functions itself.
`auth-source-xoauth2-plugin' also makes use of `oauth2.el' and its
storage for storing temporary/ephemeral data tokens, where
`auth-source-xoauth2' implemented its own storage.
[auth-source-xoauth2] <https://github.com/ccrusius/auth-source-xoauth2>
2.2 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.
