—- 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

This plugin uses OAuth2 to access the mailbox for processing bounces and for sending email using SMTP. Currently it supports OAuth2 for only Microsoft Office365 / Outlook.

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

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.

// 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();
}

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

• Tenant Id
• 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 URL will be similar to this, otherwise adjust for the actual location

https://mysite.com/lists/admin/?pi=OAuth2&page=authorise

You can select to use OAuth2, instead of the normal password verification, when sending emails using SMTP.
Currently the plugin supports having an access token for only one email address, so that email address would need to be used for both sending and receiving emails if this setting is set to Yes.

The plugin previously had settings for the IMAP mailbox/folder name, the maximum number of bounces to process, and the batch size when processing bounce rules. These have now been replaced by core phplist config.php settings added in phplist release 3.6.14.

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'

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

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)

$log_options = [
    'threshold' => 'DEBUG',
    'classes' => [
        'GuzzleHttp' => true,
    ],
];

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.

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

Each query will be logged similar to this

[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", ...

To stop logging simply change DEBUG to OFF.