emiliablasten / auth-source-xoauth2

A package that adds XOAuth2 capabilities to Emacs' auth-source infrastructure

auth-source-xoauth2

This package adds XOAuth2 authentication capabilities to auth-source.

This integration requires some preliminary work on the users’ part, which includes creating tokens that the package will use. For more details,

M-x describe-variable auth-source-xoauth2-creds

Once all tokens are obtained, adding

(auth-source-xoauth2-enable)

to your configuration will enable XOAuth2 mechanisms in both IMAP and SMTP. For more details, see

M-x describe-function auth-source-xoauth2-enable

If you want to use the package with other services, the auth-source-xoauth2-enable function will probably have to be modified to add the necessary protocol compatibility hooks: the existing contents should serve as a guide, and I would be happy to include contributions in this package.

Note: This package does work with Emacs 25.1, even though it requires 26.1 in the package description. That requirement is necessary in order to silence linter errors. If using Emacs 25.1, the auth-source-pass package is optional.

Debugging

If things are not working, the first thing to do is probably to try and get an access token manually. This can be done with curl as follows (replace the values with your particular ones, and remember to quote whatever needs quoting):

curl --request POST \
  --url 'https://oauth2.googleapis.com/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data 'client_id=<client_id>' \
  --data 'client_secret=<client_secret>' \
  --data 'refresh_token=<refresh_token>'

This should get you a reply that includes the access token. If it doesn’t, failures will hopefully include error messages that tell you what to do. In the following case, you need to re-generate the refresh token:

{
  "error": "invalid_grant",
  "error_description": "Token has been expired or revoked."
}

Obtaining Google (GMail) Tokens

This is a copy & paste of the Elisp documentation for the auth-source-xoauth2-creds variable, which may be more up-to-date than this copy.

If you are using this package to authenticate to Google, the values needed for the auth-source-xoauth2-creds variable can be obtained through the following procedure (note that Google changes this procedure every now and then, so the steps may be slightly different):

1. Go to the developer console, https://console.developers.google.com/project
2. Create a new project (if necessary), and select it once created.
3. Select “APIs & Services” from the navigation menu.
4. Select “Credentials”.
5. Create new credentials of type “OAuth Client ID”.
6. Choose application type “Other”.
7. Choose a name for the client.

This should get you all the values but for the refresh token. For that one:

1. Install the Go development tools (from https://go.dev).
2. Clone the https://github.com/ccrusius/auth-source-xoauth2 repository.
3. Execute the following command in the cloned repository:

   cd google-oauth
   make
   ./oauth -client_id <client id from previous steps> \
           -client_secret <client secret from previous steps>
       

4. Visit the URL the tool will print on the console. The page will ask you for the permissions needed to access your Google acount.
5. Once you give approval, the refresh token will be printed by the tool in the terminal. You should now have all the required values (the :token-url value should be ”https://accounts.google.com/o/oauth2/token”).”)