From 21d5b249a4e71642e3b68a8633c0f0e22da58601 Mon Sep 17 00:00:00 2001 From: Simon Robinson Date: Tue, 30 Jan 2024 17:57:14 +0000 Subject: [PATCH] Additional plugin usage examples and documentation --- emailproxy.config | 44 ++++++++++++++++++++++++++++++-------------- plugins/README.md | 1 + 2 files changed, 31 insertions(+), 14 deletions(-) diff --git a/emailproxy.config b/emailproxy.config index d796486..36ba4dc 100644 --- a/emailproxy.config +++ b/emailproxy.config @@ -39,18 +39,20 @@ documentation = Local servers are specified as demonstrated below where, for exa /etc/letsencrypt/live/mail.example.net/privkey.pem) for the server you are using the proxy with, and it will use these to set up a secure connection between itself and your email client. - Experimental feature - proxy plugins: - - Plugins are a semi-experimental new feature that enables the use of separate scripts to modify IMAP/SMTP commands - when they are received from the client or server before passing through to the other side of the connection. The - `plugins` property is a dictionary of one or more plugins, specified in the order that they should be applied to - all received data, starting after authentication succeeds. Plugins are chained, so they can both edit incoming - messages; and, use these as triggers to initiate their own communication with the server without any need to reveal - this to the client (for example: client -> p1 -> p2 -> server -> p2 -> server -> p2 -> p1 -> client). Each key of - the `plugins` property must be the name of a plugin you want to apply (note: the plugin's filename and its main - class name must be identical). Each value should either be an empty dictionary if the plugin has no setup arguments; - or, a set of key-value pairs to match the plugin's named initialisation parameters. See the [IMAP-2995] example - below, which loads the IMAPIgnoreSentMessageUpload plugin with its `target_mailboxes` configured to match Gmail's - `Sent Mail` mailbox. For further details and documentation, see the range of sample plugins. + Advanced feature - proxy plugins: + - Plugins are an advanced feature that enable the use of separate scripts to modify IMAP/POP/SMTP commands when they + are received from the client or server before passing through to the other side of the connection. The `plugins` + property is an dictionary of one or more plugins, specified in the order that they should be applied to all received + data. On the client side of the connection plugins are run in the order shown; on the server side plugins are run in + reverse order. On the server side, plugins can be used at any point, but for security reasons plugins on the client + side are inserted after authentication has succeeded. Plugins are chained, so they can both edit incoming messages; + and, use these as triggers to initiate their own communication with the server without any need to reveal this to + the client (for example: client -> p1 -> p2 -> server -> p2 -> server -> p2 -> p1 -> client). Each key of the + `plugins` property must be the name of a plugin you want to apply (note: the plugin's filename and its main class + name must be identical). Each value should either be an empty dictionary if the plugin has no setup arguments; or, + a set of key-value pairs to match the plugin's named initialisation parameters. See the [IMAP-1994] and [IMAP-1995] + entries below for example plugin configurations. For further details and documentation, see the range of sample + plugins at https://github.com/simonrob/email-oauth2-proxy/tree/plugins/plugins. [IMAP-1993] server_address = outlook.office365.com @@ -84,9 +86,23 @@ server_port = 465 local_address = 127.0.0.1 [IMAP-1994] +server_address = outlook.office365.com +server_port = 993 +local_address = 127.0.0.1 +plugins = { + 'IMAPFixO365SearchQuirks': {}, + 'IMAPIgnoreSentMessageUpload': {'target_mailboxes': ['Sent Items']}, + 'IMAPLinkDestinationRevealer': {}, + 'IMAPCleanO365ATPLinks': {} + } + +[IMAP-2994] server_address = imap.gmail.com server_port = 993 -plugins = {'IMAPIgnoreSentMessageUpload': {'target_mailboxes': ['[Gmail]/Sent Mail', '[Google Mail]/Sent Mail']}} +plugins = { + 'IMAPIgnoreSentMessageUpload': {'target_mailboxes': ['[Google Mail]/Sent Mail', '[Gmail]/Sent Mail']}, + 'IMAPDeflateCompressionRemoteEnabler': {} + } [Account setup] @@ -169,7 +185,7 @@ documentation = Accounts are specified using your email address as the section h service account with the proxy in a publicly-accessible context is not advised. You are highly encouraged to enable the proxy's secret encryption option (see `encrypt_client_secret_on_first_use` at the end of this file) and consider pre-encrypting account entries. A sample pre-encryption script is provided for reference at - https://github.com/simonrob/email-oauth2-proxy/issues/212#issuecomment-1867557029 + https://github.com/simonrob/email-oauth2-proxy/issues/212#issuecomment-1867557029. Advanced account configuration: - For most configurations the default `redirect_uri` value of `http://localhost` is correct, unless you have diff --git a/plugins/README.md b/plugins/README.md index 865c3c2..aca06b5 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -1,6 +1,7 @@ # Email OAuth 2.0 Proxy plugins Plugins are an advanced Email OAuth 2.0 Proxy feature that enable the use of separate scripts to modify IMAP/POP/SMTP commands when they are received from the client or server before passing through to the other side of the connection. This allows a wide range of additional capabilities or triggers to be added the proxy, as demonstrated in the examples below. +See the [sample configuration file](../emailproxy.config#L42) for further application examples and documentation. ## Sample plugins