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

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.

The plugin requires php version 8 and phpList version 3.6.14 or later. You also need to enable Common Plugin before enabling this plugin.

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

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

$bounce_mailbox_host = 'imap.gmail.com';
$bounce_mailbox_port = '993/imap/ssl';

instead of

$bounce_mailbox_host = 'pop3.gmail.com';
$bounce_mailbox_port = '995/pop3/ssl';

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

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

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

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

    $bounce_mailbox_user = 'xxx@gmail.com';
 
    $phpmailer_smtpuser = 'xxx@gmail.com';

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.