Merge branch 'main' into build

Author: simonrob

.github/workflows/pypi.yml

@@ -50,7 +50,7 @@ jobs:
           skip-existing: true  # avoid failing when repeating this action
 
       # sign the built packages
-      - uses: sigstore/gh-action-sigstore-python@v3.0.0
+      - uses: sigstore/gh-action-sigstore-python@v3.0.1
         with:
           inputs: >-
             ./dist/*.tar.gz

README.md

@@ -7,20 +7,20 @@ Transparently add OAuth 2.0 support to IMAP/POP/SMTP client applications, script
     <picture>
       <source width="300" media="(prefers-color-scheme: dark)" srcset="https://auth-email.com/static/img/logo-full-dark.svg">
       <source width="300" media="(prefers-color-scheme: light)" srcset="https://auth-email.com/static/img/logo-full-light.svg">
-      <img width="300" src="https://auth-email.com/static/img/logo-full.png" alt="Email-Auth logo">
+      <img width="300" src="https://auth-email.com/static/img/logo-full.png" alt="Auth-Email.com logo">
     </picture><br>
     <b>Email OAuth made simple</b><br>
-    <sub>Auth-Email.com is a unified proxy for all your OAuth 2.0 email accounts.</sub><br>
-    <sup>Use any app or client to access your accounts with ease.</sup>
+    <sup>Use any app, client or device to access your OAuth mail accounts with ease.</sup>
   </a><br><br>
 </div>
 
 
 ## Motivation and capabilities<a id="motivation-and-capabilities"></a>
 Email services that support IMAP, POP and/or SMTP access are increasingly requiring the use of OAuth 2.0 to authenticate connections, but not all clients support this method.
-This tool creates a local proxy that intercepts the traditional IMAP/POP/SMTP authentication commands and transparently replaces them with the appropriate SASL (X)OAuth 2.0 commands and credentials.
-Your email client can continue to use the `login` or `auth`/`authenticate` options, with no need to make it aware of OAuth's existence.
+This tool is a local proxy that intercepts the traditional IMAP/POP/SMTP authentication commands and transparently replaces them with the appropriate SASL (X)OAuth 2.0 commands and credentials.
+Your email client, app or device can continue to use the `login` or `auth`/`authenticate` options, with no need to make it aware of OAuth's existence.
 The proxy works in the background with a menu bar/taskbar helper or as a headless system service, and is compatible with macOS, Windows and Linux.
+It can be used with any email provider that supports OAuth 2.0 authentication, including Outlook, Office 365, Hotmail, 21Vianet, Gmail, Google Workspace, Fastmail, Yahoo, Comcast, AOL and many others.
 
 ### Example use-cases<a id="example-use-cases"></a>
 - You need to use an Office 365 email account, but don't get on with Outlook.
@@ -29,6 +29,7 @@ The email client you like doesn't support OAuth 2.0, which became mandatory [in
 - You have an account already set up in an email client, and you need to switch it to OAuth 2.0 authentication.
 You can edit the server details, but the client forces you to delete and re-add the account to enable OAuth 2.0, and you don't want to do this.
 - You have made your own script or application that sends or receives email, but it doesn't support OAuth 2.0, and you don't want to have to modify it to implement this.
+- You use a device or business application that provides functions such as scan to email, email alerts or email to print, but you can't set it up to use the official OAuth 2.0 workarounds from [Microsoft](https://learn.microsoft.com/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365) or [Google](https://support.google.com/a/answer/176600). 
 - You work with multiple services or applications that use IMAP/POP/SMTP, and you don't want to have to set up OAuth 2.0 independently for each one.
 
 In all of these cases and more, this proxy can help – just follow the instructions below to get started.
@@ -41,7 +42,7 @@ Begin by downloading the proxy via one of the following methods:
 
 <ol type="A">
   <li><b>Pick a <a href="https://github.com/simonrob/email-oauth2-proxy/releases/latest">pre-built release</a></b> for your platform (macOS or Windows; no installation needed); <i>or</i>,</li>
-  <li><b>Install from <a href="https://pypi.org/project/emailproxy/">PyPI</a></b>: set up using <code>python -m pip install emailproxy\[gui\]</code>, download the <a href="https://github.com/simonrob/email-oauth2-proxy/raw/main/emailproxy.config">sample <code>emailproxy.config</code> file</a>, then <code>python -m emailproxy</code> to run; <i>or</i>,</li>
+  <li><b>Install from <a href="https://pypi.org/project/emailproxy/">PyPI</a></b>: set up using <code>python -m pip install "emailproxy[gui]"</code>, download the <a href="https://github.com/simonrob/email-oauth2-proxy/raw/main/emailproxy.config">sample <code>emailproxy.config</code> file</a>, then <code>python -m emailproxy</code> to run; <i>or</i>,</li>
   <li><b>Clone or <a href="https://github.com/simonrob/email-oauth2-proxy/archive/refs/heads/main.zip">download</a></b> (and star :-) the <a href="https://github.com/simonrob/email-oauth2-proxy/">GitHub repository</a>, then: <code>python -m pip install -r requirements-core.txt -r requirements-gui.txt</code> to install requirements, and <code>python emailproxy.py</code> to run.</li>
 </ol>
 
@@ -87,6 +88,7 @@ The [sample configuration file](https://github.com/simonrob/email-oauth2-proxy/b
 - Gmail / Google Workspace: register a [Google API desktop app client](https://developers.google.com/identity/protocols/oauth2/native-app).
 - Outlook / Hotmail (personal accounts): If you are part of the Microsoft 365 Developer Programme or have an Azure account (including free accounts), you can create your own app registration in the Entra admin centre – see [this discussion](https://github.com/simonrob/email-oauth2-proxy/discussions/301) for a guide.
 If not, you will need to reuse an existing client ID – see, for example, [this sample configuration](https://github.com/simonrob/email-oauth2-proxy/issues/297#issuecomment-2424200404).
+- Fastmail: register a new [Fastmail OAuth client](https://www.fastmail.com/dev/#registration).
 - AOL and Yahoo Mail (and subproviders such as AT&T) are not currently allowing new client registrations with the OAuth email scope – the only option here is to reuse the credentials from an existing client that does have this permission.
 
 The proxy supports [Google Cloud service accounts](https://cloud.google.com/iam/docs/service-account-overview) for access to Google Workspace Gmail.
@@ -208,7 +210,7 @@ Please [open an issue](https://github.com/simonrob/email-oauth2-proxy/issues) if
 
 When first launching on Linux in GUI mode you may encounter errors similar to `Namespace […] not available`, issues with the task bar icon display, or no browser popup when attempting to authorise your accounts.
 This is caused by missing dependencies for [pystray](https://github.com/moses-palmer/pystray/) and [pywebview](https://github.com/r0x0r/pywebview/), which are used to display the menu bar icon and authentication windows.
-See the [pywebview dependencies](https://pywebview.flowrl.com/guide/installation.html#dependencies) and [pystray FAQ](https://pystray.readthedocs.io/en/latest/faq.html) pages and [existing](https://github.com/simonrob/email-oauth2-proxy/issues/1#issuecomment-831746642) [closed](https://github.com/simonrob/email-oauth2-proxy/issues/136#issuecomment-1430417456) [issues](https://github.com/simonrob/email-oauth2-proxy/issues/305#issuecomment-2482989955) in this repository for a summary and suggestions about how to resolve this.
+See the [pywebview dependencies](https://pywebview.flowrl.com/guide/installation.html#dependencies) and [pystray FAQ](https://pystray.readthedocs.io/en/latest/faq.html) pages and [several](https://github.com/simonrob/email-oauth2-proxy/issues/1#issuecomment-831746642) [previous](https://github.com/simonrob/email-oauth2-proxy/issues/136#issuecomment-1430417456) [closed](https://github.com/simonrob/email-oauth2-proxy/issues/305#issuecomment-2482989955) [issues](https://github.com/simonrob/email-oauth2-proxy/issues/342#issuecomment-2775313239) in this repository for a summary and suggestions about how to resolve this.
 
 A similar issue may occur on Windows with the [pythonnet](https://github.com/pythonnet/pythonnet) package, which is required by [pywebview](https://github.com/r0x0r/pywebview).
 The [pythonnet installation instructions](https://github.com/pythonnet/pythonnet/wiki/Installation) may offer alternative ways to install this package if the default installation fails.
@@ -259,6 +261,7 @@ See the [documentation and examples](https://github.com/simonrob/email-oauth2-pr
 Michael Stepner has created a [Terraform configuration](https://github.com/michaelstepner/email-oauth2-proxy-aws) that helps run this proxy on a lightweight cloud server (AWS EC2).
 Thiago Macieira has provided a [makefile and systemd configuration files](https://github.com/thiagomacieira/email-oauth2-proxy/tree/Add_a_Makefile_and_systemd_configuration_files_to_install_system_wide).
 For Docker, Moriah Morgan has an [example configuration](https://github.com/blacktirion/email-oauth2-proxy-docker).
+For Helm, Patrick Joyce has an [example chart](https://github.com/pjaudiomv/email-oauth2-proxy-helm).
 
 If you already use postfix, the [sasl-xoauth2](https://github.com/tarickb/sasl-xoauth2) plugin is probably a better solution than running this proxy.
 Similarly, if you use an application that is able to handle OAuth 2.0 tokens but just cannot retrieve them itself, then [pizauth](https://github.com/ltratt/pizauth), [mailctl](https://github.com/pdobsan/mailctl) or [oauth-helper-office-365](https://github.com/ahrex/oauth-helper-office-365) may be more appropriate.

emailproxy.config

@@ -153,8 +153,10 @@ documentation = Accounts are specified using your email address as the section h
 	2.0 flows (both currently only known to be available for Office 365). To use either of these flows, add an account
 	entry as normal, but do not add a `permission_url` value (it does not apply, and its absence signals to the proxy to
 	use the appropriate token retrieval mechanism). For CCG, set `oauth2_scope = https://outlook.office365.com/.default`
-	and `oauth2_flow = client_credentials`. For ROPCG, set `oauth2_flow = password` (and use a standard scope value). An
-	example is given for both methods towards the end of the sample account entries below.
+	and `oauth2_flow = client_credentials`. For ROPCG, set `oauth2_flow = password` (and use a standard scope value).
+	If you are using Microsoft services delivered by a regional provider (such as 21Vianet) that uses a non-standard
+	ROPCG variant, remove the `oauth2_scope` value and instead use `oauth2_resource`. Examples are given for each of
+	these cases towards the end of the sample account entries below.
 
 		- WARNING: Please note that by default the CCG flow has essentially no local access control when creating new
 		accounts (no user consent is involved, so the proxy cannot validate login attempts unless an account entry
@@ -167,11 +169,11 @@ documentation = Accounts are specified using your email address as the section h
 		script at https://github.com/simonrob/email-oauth2-proxy/issues/61#issuecomment-1259110336.
 
 	- The proxy supports the device authorisation grant (DAG) OAuth 2.0 flow (currently only known to be available for
-    Office 365 / Outlook), which may better suit headless systems. To use this flow, set `oauth2_flow = device`. With
+	Office 365 / Outlook), which may better suit headless systems. To use this flow, set `oauth2_flow = device`. With
 	this flow, the proxy receives authorisation responses directly from the service provider, so no `redirect_uri` is
 	needed. An example account configuration is given below. For additional customisation, the proxy modifications and
 	scripts demonstrated at https://github.com/simonrob/email-oauth2-proxy/pull/317 show how the DAG flow authorisation
-    message could be pushed to a separate device, which may be useful when running the proxy headless or without a GUI.
+	message could be pushed to a separate device, which may be useful when running the proxy headless or without a GUI.
 
 	Gmail customisation:
 	- The proxy supports the use of service accounts with Gmail for Google Workspace (note: normal Gmail accounts do not
@@ -211,6 +213,9 @@ documentation = Accounts are specified using your email address as the section h
 	the same address. To avoid clashes, it is recommended that each account has a unique `redirect_uri` (or
 	`redirect_listen_address`) value, for example by using a different port for each account.
 
+	- Some providers require the use of SHA-256 PKCE code challenges instead of client secrets. To use this method, set
+	`client_secret = pkce` as shown in the Fastmail example below.
+
 	Integration with a secrets manager:
 	- The proxy caches authenticated OAuth 2.0 tokens and associated metadata back into this configuration file by
 	default, but can alternatively be configured to use either a separate local file (via `--cache-store /path/to/file`)
@@ -239,6 +244,13 @@ redirect_uri = http://localhost
 client_id = *** your client id here ***
 client_secret = *** your client secret here ***
 
+[your.email@fastmail.com]
+permission_url = https://api.fastmail.com/oauth/authorize
+token_url = https://api.fastmail.com/oauth/refresh
+oauth2_scope = https://www.fastmail.com/dev/protocol-imap https://www.fastmail.com/dev/protocol-pop https://www.fastmail.com/dev/protocol-smtp
+client_id = *** your client id here ***
+client_secret = pkce
+
 [your.email@yahoo.co.uk]
 permission_url = https://api.login.yahoo.com/oauth2/request_auth
 token_url = https://api.login.yahoo.com/oauth2/get_token
@@ -271,14 +283,22 @@ oauth2_flow = client_credentials
 client_id = *** your client id here ***
 client_secret = *** your client secret here (remove this entire line if a secret is not required) ***
 
-[ropcg.flow.configured.address@your-tenant.com]
+[ropcg.flow.scope.configured.address@your-tenant.com]
 documentation = *** note: this is an advanced O365 account example; in most cases you want the version above instead ***
 token_url = https://login.microsoftonline.com/*** your tenant id here ***/oauth2/v2.0/token
 oauth2_scope = https://outlook.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/POP.AccessAsUser.All https://outlook.office365.com/SMTP.Send offline_access
 oauth2_flow = password
 client_id = *** your client id here ***
 client_secret = *** your client secret here (remove this entire line if a secret is not required) ***
 
+[ropcg.flow.resource.configured.address@your-tenant.com]
+documentation = *** note: this is an advanced O365 account example specific to providers that use a non-standard version of the ROPCG flow (such as 21Vianet); in most cases you want the version above instead ***
+token_url = https://login.partner.microsoftonline.cn/*** your tenant id here ***/oauth2/token
+oauth2_resource = https://partner.outlook.cn
+oauth2_flow = password
+client_id = *** your client id here ***
+client_secret = *** your client secret here (remove this entire line if a secret is not required) ***
+
 [service.account.accessible.address@your-domain.com]
 documentation = *** note: this is an advanced Google account example; in most cases you want the version above instead ***
 token_url = https://oauth2.googleapis.com/token