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)

2023-11-01

This release features two significant improvements contributed by @terencehonles:

• #198: Add support for encrypted secret rotation, which allows the security of locally-cached account access tokens to be automatically improved periodically when recommended.
  • Please note: in almost every case this will be a positive update, but this change does mean that encrypted credentials in the proxy's configuration files are not fully backward compatible between this version of the proxy and previous versions (i.e., opening this version's configuration file with a previous version of the proxy will lead to a re-authentication request). If you currently share a configuration file (or local/AWS --cache-store) between multiple instances of the proxy, be sure to upgrade all of these at the same time to avoid being asked to re-authenticate your accounts.
• #199 and #201: Package the proxy to support distribution as a standard Python module on PyPI, which simplifies installation in most cases, and also allows further customisation or combination with other tools.

In addition:

• #189: Add an option to disable credential censoring to help with troubleshooting (requires a script edit for safety) – thanks @ronald-wentworth and @Mrstaubsauger
• #194: Specify local_address in all sample server configurations to avoid unintentionally listening outside the local system when using the example unedited – thanks @bemoody
• #196: Catch SIGUSR1 to toggle debug mode, improve the display of full addresses in debug mode, and show connection attempts more clearly – thanks @deepjansari

2023-09-06

• #155: Explicitly handle concurrent configuration file access – thanks @fpl
• #170: Update pywebview version to resolve a macOS issue – thanks @Draykan
• #175: Proactively update the GUI menu whenever new catch-all accounts are added – thanks @Draykan (and subsequently #190: fix a regression caused by this change – thanks @ray-magini)
• #179: Switch to :: (i.e., dual-stack loopback) as the default local_address when no value is specified – thanks @bwbug and @mtlg
• #183: Improve handling of expired access tokens when the refresh token is still valid – thanks @Draykan
• #185: Improve error messages when there is a possible encryption mismatch – thanks @manu-msf
• #186: Link to an improved Docker example – thanks @blacktirion
• #187: Use an inverse colour icon when starting in a light Windows theme – thanks @bwbug
• Add an icon for PyInstaller builds
• Format IPv6 addresses more clearly (surround with [] consistently)
• Improve documentation about IPv4 vs. IPv6 support and defaults
• Provide a more helpful error message when a local certificate/key is specified but not found
• Make sure stdin exists before checking it is a TTY
• Work around an incompatibility when using pystray <= 0.19.4 with PIL >= 10.0.0