PHP: todo:ext:imap:xoauth2

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
Google and Microsoft intend to [[https://www.bleepingcomputer.com/news/security/google-to-force-oauth-in-g-suite-to-increase-security/|stop support for password-based login to IMAP and POP]], beginning on [[https://gsuiteupdates.googleblog.com/2019/12/less-secure-apps-oauth-google-username-password-incorrect.html|2020-06-15]] and [[https://developer.microsoft.com/en-us/office/blogs/end-of-support-for-basic-authentication-access-to-exchange-online-apis-for-office-365-customers/|2020-10-13]], respectively. The alternative, OAuth2-based login, will continue to work as the only means to authenticate users to these providers' mail servers.

Applications using the PHP IMAP extension for IMAP and POP access do not currently have a means to present OAuth tokens for authentication. This means that these applications will no longer be able to access Google and Microsoft email over IMAP and POP after these dates. We, the maintainers of the IMAP extension, do not wish to see our users lose access, so we are expediting the addition of token-based authentication.

==== What's This All About? ====

Currently, to access a Google-hosted inbox using the PHP IMAP extension, you do something like this:

<code php>
$mbh = imap_open('{imap.gmail.com:993/imap/ssl/}INBOX', $username, $password);
if (! $mbh) {
    error_log(imap_last_error());
    throw new \RuntimeException('Unable to open Google INBOX');
}
</code>

This is classic password-based authentication, which Google (rightly) considers less secure than a time-limited, token-based authentication. In fact, to even get the above code to work, you need to instruct Google to allow "Less Secure Apps". A similar situation applies for Microsoft 365, just the terminology is a bit different.

When these providers stop support for passwords, the above code will no longer work, period. Instead, the application will first need to register with Google as an application, then update its code to acquire an access token, then pass the access token to the IMAP server instead of the password.

The new code is substantially more complicated. I'll give an outline here (refer to the [[https://developers.google.com/identity/protocols/OAuth2|Google OAuth 2 documentation]] for more detail including a diagram):

  - Create a login link that includes your application's registered ID and a nonce, scoped to the email service for Google.
  - Redirect your user to this link, which will prompt them to confirm the share.
  - Google redirects back to you with the same nonce and an authorization code.
  - Verify the nonce matches, then use the authorization code to generate an access token an d a refresh token.
  - Store the refresh token.
  - Pass the access token to the [[https://www.php.net/manual/en/function.imap-open.php|imap_open]] function call. See below, under Our Plan.

For more on OAuth, refer to this [[https://aaronparecki.com/oauth-2-simplified/|OAuth primer by Aaron Parecki]].

==== What You Need to Do ====

If you are the author of a PHP application using imap_open to access Google or Microsoft IMAP or POP servers, then you need to:

  - Update your application to support OAuth flows. A general sketch is given above, but you'll need to support:
    - session storage of nonce and access tokens per user
    - persistent, secure storage of refresh tokens per user
    - redirection to, and from, Google or Microsoft
  - Update your imap_open call to pass the access token

In addition:

  - Contact Google and Contact Microsoft and ask them to extend the deadline. The more time we have to migrate, the better.

Don't forget:

  - Support the development of this feature by:
    - Voting or commenting on [[https://bugs.php.net/bug.php?id=64039|Issue #64039]]
    - [[mailto:bishop@php.net|Share your questions with me]]
    - [[https://www.patreon.com/cerebriform|Fund a little bit of my time]] to get this done


==== Our Plan ====

As you can see, this is not just a drop-in replacement. Once your application can speak an OAuth flow, then you need to pass the token to imap_open. We have some work to do here:

  - Improve imap_open to accept OAuth tokens (see below for sample)
  - Open RFC to backport this feature into all [[https://www.php.net/supported-versions.php|supported PHP versions]], including security fix branches
    * Normally these branches don't receive features
    * However, if they don't, you'll have to patch your install manually -- and that's not ideal
  - Provide a pure PHP example using curl and imap extensions to provide OAuth authentication
  - Support the community by FAQ, Q&A, etc.

=== Proposed API Change ===

The plan is to add token support to imap_open, as follows:

<code php>
$mbh = imap_open($server, $username, $token, OP_XOAUTH2);
if (! $mbh) {
    error_log(imap_last_error());
    throw new \RuntimeException('Unable to open Google INBOX');
}
</code>

Here, the parameter described as "password" takes the token received from the OAuth flow, and the function's told it's a token by the newly added option OP_XOAUTH2. Internally, this will cause the function to use the XOAUTH2 mechanism during the AUTHENTICATE sequence, which is transparent to consumers.

=== Future Direction ===

OAuth 2 supports an extra challenge phase, whereby one has to supply multi-factor authentication beyond just the token. In this first implementation, because of the looming deadline, imap_open will not support this. However, a future implementation might, using an API like follows:

<code php>
$options = [];
if ($_GET['mfa']) {
    $options['OP_XOAUTH2_CHALLENGE'] = $_GET['mfa'];
}
$mbh = imap_open($server, $username, $token, OP_XOAUTH2, $max_retries, $options);
if (! $mbh) {
    if (IMAP_XOAUTH2_CHALLENGE === imap_last_error_code()) {
        // show form collecting MFA into 'mfa' variable
    } else {
        error_log(imap_last_error());
        throw new \RuntimeException('Unable to open Google INBOX');
    }
}
</code>

The basic idea is to first try an OAuth authentication. If that fails, prompt the user to enter their MFA, then on the next submission, pass the challenge value to the open.

=== Work in Progress ===

This is a work in progress. Plan changes will be posted here. Status reports will be [[http://cerebriform.blogspot.com/|blogged]]. Feel free to [[mailto:bishop@php.net|ask a question]].
Page Tools
