2025-06-25

Email OAuth 2.0 Proxy is sponsored by


Email OAuth made simple
^{Use any app, client or device to access your OAuth mail accounts with ease.}

This release is kindly sponsored by Auth-Email.com – a hosted OAuth 2.0 email proxy service that takes the hassle out of authenticating your email accounts.

Recent changes:

• Don't override client_secret when using PKCE. This release changes the recently-added PKCE capability to remove the use of a specific client secret value ('pcke'), and instead adds a new account configuration attribute use_pkce = True which can be added to enable this behaviour. This change adds support for providers such as Comcast which require PKCE in addition to a client secret. Thanks to Nick from Auth-Email.com for pointing out this issue.

---

Important note about pre-built executables

Please note that the pre-built executables provided here are packaged automatically directly from the source using PyInstaller and Nuitka. There is no difference between these versions except for the way in which they are packaged, so it is fine to choose either option. However, while these versions of the proxy are provided for your convenience, they are not officially supported. In addition, it is possible that you will see false positive warnings about these files (from, e.g., Microsoft Defender). This is not an issue with the proxy itself, but if it helps you are welcome to report this problem to the various scanning providers (e.g., see this previous discussion), which normally resolves the alert for that version of the proxy.

2025-06-24

Email OAuth 2.0 Proxy is sponsored by


Email OAuth made simple
^{Use any app, client or device to access your OAuth mail accounts with ease.}

This release is kindly sponsored by Auth-Email.com – a hosted OAuth 2.0 email proxy service that takes the hassle out of authenticating your email accounts.

Recent changes:

• #349: Specify the default backend for loading JWT X.509 fingerprints to maintain compatibility with older versions of cryptography – thanks @dabaer
• #342: Additional Linux GUI dependency setup documentation – thanks @strikegun79
• #351: Support a non-standard variant of ROPCG used by 21Vianet, and more robustly handle cases where expires_in is not returned as an integer – thanks @Eric-ZhehanZ
• #357: Fix a configuration file path issue when using Nuitka – thanks @Selwoir for reporting
• #360: Add link to example Helm Chart – thanks @pjaudiomv
• Better debug logging of JSON message content when token-related errors occur
• Add support for PKCE code challenges (required by Fastmail and Comcast; optional for various other providers/configurations)

Please note that the pre-built executables provided here are packaged automatically directly from the source using PyInstaller and Nuitka. There is no difference between these versions except for the way in which they are packaged, so it is fine to choose either option. However, while these versions of the proxy are provided for your convenience, they are not officially supported. In addition, it is possible that you will see false positive warnings about these files (from, e.g., Microsoft Defender). This is not an issue with the proxy itself, but if it helps you are welcome to report this problem to the various scanning providers (e.g., see this previous discussion), which normally resolves the alert for that version of the proxy.

2025-03-14

Email OAuth 2.0 Proxy is sponsored by


Email OAuth made simple
_{Auth-Email.com is a unified proxy for all your OAuth 2.0 email accounts.}
^{Use any app or client to access your accounts with ease.}

This release is kindly sponsored by Auth-Email.com – a hosted OAuth 2.0 proxy service that takes the hassle out of authenticating your email accounts.

Recent changes:

• #317: Point to potential advanced usage of the device authorisation grant flow – thanks @a-ilin
• #321: Reject blank passwords during login – thanks @DiablosOffens
• #322: Improve version naming variables for the benefit of external parsers – thanks @jameshilliard, @airtower-luna and @vfazio
• #330: Add auto-built executable created with Nuitka in addition to the existing PyInstaller approach to work around various false-positive issues – thanks @sommerf-lf
• Support SASL additional data challenges when errors occur during login
• Increase cryptographic iterations to match the latest recommendation as of January 2025
• Various documentation improvements – thanks @wtcline-intc
• Various minor lint fixes, and better handling of lint warnings in no-GUI installations

Please note that the pre-built executables provided here are packaged automatically directly from the source using PyInstaller and Nuitka. These versions of the proxy are provided for convenience, but are not officially supported. In addition, it is possible that you will see false positive warnings about these files (from, e.g., Microsoft Defender). This is not an issue with the proxy itself, but if it helps you are welcome to report this problem to the various scanning providers (e.g., see this previous discussion).

2024-11-11

• #302: Add support for the Device Authorisation Grant OAuth 2.0 flow – many thanks to @a-ilin for contributing to this feature
• #286: Better missing GUI requirements message on macOS – thanks @kourosh2
• Documentation improvements to help better navigate the plethora of different OAuth 2.0 configurations, and address common misconfigurations.
• Fix a compatibility issue with pywebview 5.3+
• Various minor lint fixes

Please note that the pre-built executables provided here are packaged automatically directly from the source using PyInstaller. It is possible that virus scanners will raise false positive warnings about these files. If it helps you are welcome to report this problem to the various virus scanning providers (e.g., see this previous discussion).

2024-09-12

• #271: New configuration option use_login_password_as_client_credentials_secret that enables using the IMAP/POP/SMTP login password as the client_secret value for O365's Client Credentials Grant (CCG) flow – thanks @Geod24
• Documentation and configuration example improvements – thanks @wtcline-intc, @rqi14, @SnakeSK, @whitedavidp and @bwbug
• Various minor lint fixes

2024-05-25

• #247: Add support for JWT assertions (certificate credentials) – thanks @jannispl for contributing this feature
• #242: Work around Ubuntu python-pywebview bug – thanks @wtcline-intc

2024-03-15

Many thanks to @Ar-4t for generously sponsoring an enhancement that is included in this release:

• #236: Support local STARTTLS for SMTP connections.

  The proxy has long supported server-side SMTP STARTTLS, but has previously required this to be handled by itself (rather than the email client) in order for it to be able to intercept and authenticate the connection. Some clients require secure local connections, but only support this via STARTTLS, however, and previously these could not be used with the proxy directly. This feature adds a new local_starttls configuration parameter, used in conjunction with local_certificate_path and local_key_path.

  As part of this change, the existing starttls configuration parameter has been renamed to server_starttls to avoid confusion going forward. Updating existing configuration files is recommended to avoid confusion, particularly if both options are enabled, but the original value will continue to be supported – starttls = True will always enable server-side STARTTLS.

This release also contains the following improvements/fixes:

• #215: Better handling of getaddrinfo results – thanks @jlevon
• #228: Allow failed local authentication attempts to be retried (rather than closing the connection immediately) – thanks @bemoody
• #237: Support servers that return strings for expected integer values in their token response – thanks @FlashIvano
• Better handling of parse errors in configuration files

2024-01-20

Many thanks to @sertys3 for generously sponsoring an enhancement that is included in this release:

• #212: Support authenticating Google Workspace Gmail accounts using a Google Cloud service account

This release also contains the following improvements/fixes:

• #213: Avoid looping indefinitely on encrypted secret decryption failure (mostly applicable in client credentials grant (CCG) mode) – thanks @ft3411
• Allow token_salt and token_iterations values to be inherited for use in catch-all account configurations (e.g., CCG accounts that all use the same password)
• #214: Clarify security documentation for CCG (and Google service account) mode, explaining the potential risks; and, prevent these methods from using the delete_account_token_on_password_error option – thanks @gerneio
   
  Please note that as a result of #214, this version of the proxy now requires an oauth2_flow value to be set explicitly when using a method that does not require a permission_url (previously the default was to fall back to the CCG flow). This will not have any impact if you have already specified a value for this property, as is shown in the example configuration file. If you have not specified a value, and intend to use the CCG flow, you should add oauth2_flow = client_credentials to the account(s) in question in the proxy's configuration file.

In addition:

• Three CodeQL-recommended improvements
• Include extra feature dependencies in Windows and macOS pre-built versions to to ensure all capabilities can be used (i.e., for AWS caching features and Google Cloud service accounts)
• Import certifi to ensure SSL certificates are available when packaged by pyinstaller using GitHub Actions
• Work around macOS App Translocation when packaged by pyinstaller by providing a default config file path that doesn't rely on the app's location (~/.emailproxy/emailproxy.config)
• Explicitly set a timeout for authentication URL requests

2023-12-19

This release contains the following security update, which applies specifically to usage of the proxy with O365 and the client credentials grant (CCG) flow:

• Fix an issue where expired tokens could be renewed automatically without checking their validity against the original account configuration.
   
  When using the CCG flow, an attacker with knowledge of valid account addresses and careful timing (i.e., attempting to log in during a period from 10 minutes prior to the token expiry time, but before a valid login is received) could use this to gain access to an account.
   
  If you use this flow, but have also set encrypt_client_secret_on_first_use = True and removed the original client_secret value from the proxy's configuration file then this issue is not a concern.
   
  The CCG authentication flow is a specialist non-default use-case that requires extra configuration, and for most users of the proxy this issue will not be a concern. However, if you are using this flow – particularly if this is in a publicly-accessible context – upgrading is highly recommended.

Thanks to @gerneio for prompting further investigation of the CCG flow implementation, which led to the discovery of this issue. In addition, thanks to @w5pny and @Profex for pointing out that this release reports the wrong version string (2023-11-19 rather than 2023-12-19). This oversight has no affect on the proxy or the security fix, and there is now a pre-commit hook to make sure version numbers are always updated in future.

2023-11-18

• Fix three regressions caused by the changes made in preparation for packaging the proxy as a Python module:
  • #204: Startup in --no-gui mode failed when the GUI dependency pystray was present but broken – thanks @w5pny
  • #206: Prompt toolkit was not available globally, so --external-auth using this method was broken – thanks @roboshim
  • Make sure log file output and auto-start features properly handle packaged versions of the proxy
• #205: Remove unnecessary whitespace in the sample configuration file – thanks @brianjmurrell
• Fix an incorrect import (that previously only worked because pystray provided the correct import)