auth-source-xoauth2

auth-source-xoauth2 copied to clipboard

#+TITLE: auth-source-xoauth2 #+AUTHOR: Cesar Crusius #+OPTIONS: num:nil

[[http://melpa.org/#/auth-source-xoauth2][http://melpa.org/packages/auth-source-xoauth2-badge.svg]]

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,

#+BEGIN_EXAMPLE M-x describe-variable auth-source-xoauth2-creds #+END_EXAMPLE

Once all tokens are obtained, adding

#+BEGIN_EXAMPLE (auth-source-xoauth2-enable) #+END_EXAMPLE

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

#+BEGIN_EXAMPLE M-x describe-function auth-source-xoauth2-enable #+END_EXAMPLE

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.

#+BEGIN_NOTE Disclaimer: This is not an officially supported Google product. #+END_NOTE

• 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):

#+BEGIN_SRC shell 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>' #+END_SRC

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:

#+BEGIN_EXAMPLE { "error": "invalid_grant", "error_description": "Token has been expired or revoked." } #+END_EXAMPLE

• Obtaining Google (GMail) Tokens

#+BEGIN_QUOTE 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. #+END_QUOTE

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:

   #+BEGIN_SRC shell cd google-oauth make ./oauth -client_id
   -client_secret #+END_SRC

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]]").")