| Help for Alpine - XOAUTH2 |
| You are in Home > Miscellaneous > XOAUTH2 |
XOAUTH2 is a special way in which you allow a program access to your data. The idea of XOAUTH2 is to create the illusion of security by allowing only temporary access to a user to their own data.
The idea is simple. If a user can authenticate to a server, then that user is given a key that allows the user to create temporary passwords. These passwords are only valid for a short period of time and they must be renewed constantly in order for the user to keep having access to their data. This revalidation is done without the user intervention.
The key given by the server must be saved securely. If you share that key you are sharing access to your data, so all efforts must be made to keep that key secure. However note that many services attach the key to your computer, which means that transfering the key to another computer will invalidate the key, and hence cannot be used to generate temporary passwords.
Because of the above, when Alpine is asking for authorization to access your data, always open the URL in a browser in the same computer that you are running Alpine and do not take the URL to another computer.
In order for Alpine to use XOAUTH2 the server it is connecting to must support it. This is typically advertised as a capability of the server. In the case of IMAP, the server must advertise AUTH=XOAUTH2 in the set of capabilities. In the case of a POP3 server it must respond with XOAUTH2 to the CAPA command, and in the case of SMTP it must have XOAUTH2 in the AUTH capability as a reply to the EHLO command.
In addition, Alpine must be registered with the provider of the service. Alpine is only registered with all the providers listed in this page.
If you want to force Alpine to use XOAUTH2 you must add /auth=xoauth2 to the setting of the server. For example, if your old settings were server.com/ssl, then now they will be server.com/ssl/auth=xoauth2. However, please note that you must use the name of the server as stated in this page for each provider. See each provider for the specific settings in each case.
If you do not specify the /auth=xoauth2 flag, Alpine will try to aunthenticate to the server using the methods it knows that are also supported by the server, and will attempt each method in the order in which they were compiled into the binary. Since XOAUTH2 is the last method, this means that other methods that use the username and password combination will be attempted first, so if you do not want Alpine to ask you for your password you must add /auth=xoauth2 or disable the other methods of authentication (it is usually better to just add /auth=xoauth2 than to disable other authentication methods, since that disables a method for all connections, and that might be desirable in some cases and undesirable in some others.)
Please note that in order to use XOAUTH2 you must add /auth=xoauth2 to every setting that you use to connect to that server. This could include more than your INBOX path and your SMTP server. For example, it could include your folder collections, address book, remote pinerc, certificate containers, etc. If any of them stops working because your administrator disabled the PLAIN authenticator, check your settings to make sure that /auth=xoauth2 is already part of the settings for the server.
When you want to start the process of authorizing Alpine access to your email Alpine will ask you to open a URL which has been constructed based on data given by the provider (a web site) and the requirements to start that process (typically the client-id of Alpine in that site and other information). You will be asked to open that URL and follow the directions.
Once you have opened that URL you will typically login to the site with your credentials for that site. After you have done that successfully you will be shown the permissions that you will grant Alpine. They typically include the ability to save a key the server will generate so you do not have to repeat this process again every time you sign in to your email, and permissions to read, write, delete and send email. These are the minimum requirements that are needed so you can continue using Alpine the way you used to in the past.
There are two types of flows supported by Alpine to log you into a provider. One is called the Authorize and the other the Device flow. At this time the Device flow is only supported by Outlook, and it is the default flow in that case. For all other services the Authorize flow is the default. Users can use the Authorize flow with Outlook but users need to provide their own client-id and client-secret in this case.
If you are using the Authorize flow, then after you have authorized Alpine access to your email, you wil be given a code, which you must enter into Alpine. This code is sent by Alpine internally (without you noticing) to the service that you want to login and as a result Alpine receives a key (called the refresh token) and a temporary password (called the access token) that Alpine can use to login to the IMAP or SMTP server.
If you are using the Device flow, then once you have authorized Alpine you need to go back to Alpine and wait for it to get a refresh and access tokens automatically from the service to which you just authorized Alpine into.
In any case, once Alpine has obtained a refresh and access tokens it will typically ask you to save them in your password file. If you do not have a password file or do not save this information in your password file, you will have to repeat all the previous steps to authorize Alpine again the next time you try to login to the server. Because of this, make sure your version of Alpine was compiled with password file support.
When Alpine is given an access token it also receives how long this token will last before a new one needs to be requested. Alpine saves the time that this token will expire and every time it attempts to open your mailbox it checks if the token has already expired. In case it has expired Alpine uses the refresh token to ask the service provider to generate a new access token. This is done without user intervention so users do not see this part of the process.
What happens once an access token expires and you are still logged in to your account depends on the service. Some servers close the connection and ask you to login again (by generating a new access token from the refresh token) and some others continue giving you access to your email. Given that there is a chance that your connection might be closed Alpine (since version 2.24) requests a new access token once it realizes that the one it is using is about to expire, and this way your connection to the server remains open (but internally Alpine generates a new access token, creates a new session with the new access token and replaces the old session with the new session silently, without the user noticing.)
Alpine started supporting XOAUTH2 authentication for Gmail in version 2.22. The basic directions that you have to use to authorize Alpine to access your Gmail account have not changed much since then. The directions in this page are focused on how to configure the latest release of Alpine to be used with Gmail, but will likely work for previous versions of Alpine. The improvements in later versions of Alpine were improvements to the interface, rather that fixes for Gmail support.
Having said this, I have had to modify the directions to set up Alpine with Gmail several times because Google does not allow me to get a client-id and client-secret for Alpine that will work for all users, but will ask every user to get their own client-id and client-secret. This adds a layer of complexity and the exact directions depend on how Google wants users to get their client-id and client-secret. This page contains exact directions on how to do that and I am not confident that these directions will not have to be modified in the future. These directions are good at the moment of this writing. If they stop working, please let me know so I can update them.
The process you will have to follow can be roughly divided into three steps.
Fortunately Google allows you get your own Client-Id and Client-Secret. There is a moment later on that you will have to make a decision based on if you are registering Alpine for reading email in a personal Gmail account, or if you are registering Alpine to read school or work email. The process for both cases is very similar, and we will explain the differences below.
If you are getting a client-id and client-secret to access email in your organization (school or work, generally referred to as a G-Suite, or Google Workspace account), then Alpine becomes an internal app, and if you are getting a client-id and client-secret to access your personal email, then Alpine becomes an external app.
Each of the links in the next steps will take you to a full explanation, with images, on how to accomplish that specifc step.
In addition, professor Martina Morris was very kind to contribute the following directions. Her directions are very relevant in the windows operating system but they can be adapted very easily to a unix-like environment. Professor Morris had to overcome the issue that she could not configure Alpine to use xoauth2 until she edited the pinerc file, but she could not edit the pinerc file because she had not configured xoauth2, and these directions show how to overcome this issue.
Alpine started supporting XOAUTH2 authentication for Outlook in version 2.23. Originally only the device method was added and the directions to authorize Alpine have not changed at all since the first implementation. The ability to use the Authorize method in Outlook was added in version 2.24.
The process to set up Outlook or Office 365 is much simpler, and is descibed in Setting Up Alpine with Outlook.
Alpine started supporting XOAUTH2 authentication for Yahoo! in version 2.24.
The process to set up Yahoo uses the authorize method. In order to use XOAUTH2 with Yahoo! set up your inbox-path and smtp servers as follows
inbox-path = {imap.mail.yahoo.com/ssl/user=yourid@yahoo.com/auth=xoauth2}INBOX
smtp-server = smtp.mail.yahoo.com/ssl/user=yourid@yahoo.com/auth=xoauth2
You can replace /auth=xoauth2 by /auth=oauthbearer, if you wish. Alpine supports both methods.
Once you have followed the link given to you by Alpine, and authorized Alpine to access your email, you will be given a code. Copy the code, close the window where you were given the code, and enter the code into Alpine.
Alpine will use the code you obtained to obtain a refresh token and your first access token.
Alpine started supporting XOAUTH2 authentication for Yandex in version 2.24.
The process to set up Yandex is very similar to setting up XOAUTH2 with Gmail, and is descibed in detail at Setting Up Alpine with Yandex.
Setting up Alpine with other providers (such as AOL, for example) is not possible at this time. If you know of documentation that will let me add support for any other providers, please let me know. Thank you.
Sometimes you will want to revoke your permission for Alpine to access your email. Follow the directions below for each of the services you can set up XOAUTH2 with Alpine.
Revoking permission in Gmail
To revoke permissions for Alpine in Gmail follow these directions
Revoking permission in Outlook
First decide if your account is a personal account or a employer
account.
Revoking permission in Yahoo!
To revoke permissions for Alpine in Yahoo! follow these directions
Revoking permission in Yandex
To revoke permissions for Alpine in Yandex follow these directions
| You are in Home > Miscellaneous > XOAUTH2 |