phpList Resources

User Tools

Site Tools

You are here: start » plugin » oauth2
plugin:oauth2

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
plugin:oauth2 [2022/11/19 08:41]
duncanc [Logging HTTP requests and responses] 		plugin:oauth2 [2023/10/19 08:19] (current)
duncanc [The Settings page]
Line 1: Line 1:
 +====== 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 only Microsoft Office365 / Outlook.
 +
 +===== 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 =====
 +
 +==== Change 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>
 +
 +==== 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
 +
 +  * 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.
 +
 +
 +===== 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.
 +
  
plugin/oauth2.txt · Last modified: 2023/10/19 08:19 by duncanc

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial 4.0 International
CC Attribution-Noncommercial 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki
Quick Links
Resources
Contact Us

e: info@phplist.com

Boring Bit

phpList is a registered limited company

UK Company No. 07582966

VAT Registration 122 0788 37

© phpList 2016