====== OAuth2 plugin ======

---- plugin ----

description: 
author     : duncanc  
type       : 
lastupdate : 2022/11/08 21:19
compatible : 
depends    : 
conflicts  : 
similar    : 
tags       : 

downloadurl: http://github.com/bramley/phplist-plugin-oauth2/archive/master.zip

----

===== Purpose =====

This plugin uses OAuth2 to access the mailbox for processing bounces and for sending email using SMTP.

Currently it supports OAuth2 for Microsoft Office365 / Outlook and for Google Apps/Gmail.

===== Installation =====

You need to enable Common Plugin before enabling this plugin and should update Common Plugin to the latest version. On the Manage Plugins page use this package URL
  https://github.com/bramley/phplist-plugin-common/archive/master.zip

Install this plugin using the package URL
  https://github.com/bramley/phplist-plugin-oauth2/archive/master.zip



===== Configuration =====

==== Changes to config.php ====

The OAuth2 Redirect URL is used to pass control back to the application, phplist in this case. For this to work properly with phplist you need to add these lines to the config.php file, at the end is fine. This code sets the "samesite" cookie setting to "None" to allow the browser to redirect back to phplist.

<code php>
// for OAuth2 plugin
if (isset($_GET['page']) && $_GET['page'] == 'authorise' && $_GET['pi'] == 'OAuth2') {
    ini_set('session.name', 'phpListSession');
    setcookie(
        'phpListSession',
        $_COOKIE['phpListSession'],
        ['expires' => 0, 'path' => '/', 'secure' => true, 'httponly' => true, 'samesite' => 'None']
    );
    session_start();
}
</code>

=== Use IMAP instead of POP3 ===
The plugin uses a package, php-imap2, to retrieve emails from the mailbox. Unlike the php IMAP extension the package does not support POP3, only IMAP. Therefore the mailbox connection settings in config.php will probably need to be changed. For example for Gmail use

<code php>
$bounce_mailbox_host = 'imap.gmail.com';
$bounce_mailbox_port = '993/imap/ssl';
</code>

instead of 

<code php>$bounce_mailbox_host = 'pop3.gmail.com';
$bounce_mailbox_port = '995/pop3/ssl';</code>
==== The Settings page ====

After enabling the plugin there will be an OAuth2 group on the Settings page. You need to enter the fields used when registering the application with Microsoft or Google

  * Tenant Id (only for Microsoft)
  * Client Id
  * Client Secret
  * Redirect URl - this needs to be the URL of a specific page provided by the plugin.


If phplist is installed in the default location then the Redirect URL will be similar to this, otherwise adjust for the actual location
  https://mysite.com/lists/admin/?pi=OAuth2&page=authorise


=== Redirect URL with Microsoft Azure ===

Microsoft has restrictions on whether the redirect URL may contain query parameters, see [[https://learn.microsoft.com/en-gb/entra/identity-platform/reply-url#query-parameter-support-in-redirect-uris]]

If your account means query parameters in the redirect URL are not allowed then the default value shown above will be rejected when you try to add it within Azure. You will need to use an htaccess redirect rule to work-around this.

In Azure set the redirect URL to something similar to ''%%https://mysite.com/OAuth2/authorise%%'' then add a rewrite rule to the .htaccess file in the web root directory but adjust if phplist is not installed in the default location

<code>
# OAuth2 plugin
RewriteCond %{REQUEST_URI}  "/OAuth2/authorise"
RewriteRule ^(.*)$ https://mysite.com/lists/admin/?pi=OAuth2&page=authorise [R=307,L,QSA]
</code>

=== Use Oauth2 when sending using SMTP ===

You can select to use OAuth2 verification, instead of the normal password verification, when sending emails using SMTP.

Currently the plugin supports having an access token for only one email address, therefore that email address must be used for both sending and receiving emails if this setting is set to Yes. In the config.php file these two values would need to be the same
<code php>
    $bounce_mailbox_user = 'xxx@gmail.com';

    $phpmailer_smtpuser = 'xxx@gmail.com';
</code>

===== Usage =====

The plugin adds two pages to the System menu

**OAuth2 access token ** - this page shows an existing access token and its expiry time. You can sign-in to create a new access token or refresh the current token.
When you sign-in it must be with the email address used in config.php ''$bounce_mailbox_user''

**Process bounces using OAuth2** - this page will run the phplist processbounces page but will use the access token instead of a password. The php IMAP extension need not be enabled, although this page should work even when IMAP is enabled.

In the config.php file the value for ''$bounce_mailbox_password'' does not matter because it will be replaced by the access token.

The page will refresh the access token if it has already expired.

The page can also be run from the command line 

    php /path/to/phplist/admin/index.php -p processbouncesoauth2 -m OAuth2 -c /path/to/config.php
    
or as a remote page using curl or wget similar to this

    curl 'https://mysite.com/lists/admin/?page=processbouncesoauth2&pi=OAuth2&secret=xxxx'


=== Send emails using OAuth2 ===

When the configuration setting is enabled, OAuth2 authentication will be used instead of password authentication when sending emails.

===== Logging HTTP requests and responses =====

The plugin can log the HTTP requests made and responses received.

Add the following to the config.php file (at the end of the file is ok)

<code php>$log_options = [
    'threshold' => 'DEBUG',
    'classes' => [
        'GuzzleHttp' => true,
    ],
];</code>

Now requests and responses will be logged to a file in the phplist temporary directory, identfied by the ''$tmpdir'' variable in config.php. The file will be named for the current day, e.g. log_2022-11-19.txt.

Alternatively you can specify a particular directory for the log file. The directory must be writeable by the web server process.

<code php>$log_options = [
    'threshold' => 'DEBUG',
    'classes' => [
        'GuzzleHttp' => true,
    ],
    'dir' => '/path/to/directory',
];</code>

Each query will be logged similar to this

<code>
[Fri 18 Nov 2022 15:22:07] [debug] GuzzleHttp\Promise\FulfilledPromise::GuzzleHttp\Promise\{closure}, line 41
Request GET https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration?appid=xxxxx
[Fri 18 Nov 2022 15:22:07] [debug] GuzzleHttp\Promise\Promise::callHandler, line 204
Response 200 {"token_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/token","token_endpoint_auth_methods_supported":["client_secret_post","private_key_jwt","client_secret_basic"],"jwks_uri":"https://login.microsoftonline.com/common/discovery/v2.0/keys?appid=xxxxx", ...

</code>

To stop logging simply change ''DEBUG'' to ''OFF''.