Improve CCG documentation; require oauth2_flow to be set

See #214

Author: simonrob

emailproxy.config

@@ -121,15 +121,17 @@ documentation = Accounts are specified using your email address as the section h
 	- The proxy supports the client credentials grant (CCG) and resource owner password credentials grant (ROPCG) OAuth
 	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). An example is given at the end of the sample account entries below.
-	The CCG flow is the default in this mode; to specify the ROPCG flow add `oauth2_flow = password` in your account
-	configuration, and use a normal `oauth2_scope` value rather than the CCG-specific `.default`. Please note also that
-	Office 365's CCG flow does not support SMTP, and by default it has essentially no local access control when using
-	IMAP/POP in this mode (no user consent is involved, so the proxy cannot validate passwords). Because of this, you
-	are encouraged to enable the proxy's secret encryption option - see `encrypt_client_secret_on_first_use` at the end
-	of this file. In addition, if you are using the proxy in an environment where there is any possibility of malicious
-	access attempts before the first valid login then pre-encrypting account entries is highly recommended - see the
-	example setup script at https://github.com/simonrob/email-oauth2-proxy/issues/61#issuecomment-1259110336.
+	use the appropriate token retrieval mechanism). An example is given for both methods 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
+		already exists its configuration file). This is especially important when using the proxy's catch-all feature
+		(which is likely to be the case given the typical use-cases for the CCG flow). Because of this, 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. In addition, if you are using the proxy in an environment where there is any possibility of
+		malicious access attempts before the first valid login, pre-encrypting account entries is highly recommended.
+		See the example script at https://github.com/simonrob/email-oauth2-proxy/issues/61#issuecomment-1259110336.
 
 	Advanced account configuration:
 	- For most configurations the default `redirect_uri` value of `http://localhost` is correct, unless you have
@@ -181,7 +183,7 @@ redirect_uri = http://localhost
 client_id = *** your client id here ***
 client_secret = *** your client secret here ***
 
-[ccg.or.ropcg.[email protected]]
+[[email protected]]
 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/.default
@@ -190,6 +192,15 @@ redirect_uri = http://localhost
 client_id = *** your client id here ***
 client_secret = *** your client secret here ***
 
+[[email protected]]
+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
+redirect_uri = http://localhost
+client_id = *** your client id here ***
+client_secret = *** your client secret here ***
+
 [Advanced proxy configuration]
 documentation = The parameters below control advanced options for the proxy. In most cases you will not need to modify
 	the values in this section. If any of these values are not found, the proxy will assume the default value, which
@@ -210,13 +221,16 @@ documentation = The parameters below control advanced options for the proxy. In
 	cached access tokens) using the password that is given when accessing an account via IMAP/POP/SMTP. It does not do
 	this for values that are not sensitive. In the most common operation mode (i.e., interactively authorising account
 	access), the `client_secret` value falls into this category - it is not actually secret, and there is no real need
-	to prevent access to it. However, when using the Office 365 client credentials grant flow there is no user involved,
-	and possession of the secret grants full access to an account. If you use this method and it is possible that others
-	may gain access to the proxy's configuration file, set `encrypt_client_secret_on_first_use` to True and the proxy
-	will replace the `client_secret` value with a new property `client_secret_encrypted` at the next token refresh. Note
-	that this option is not compatible with `allow_catch_all_accounts` unless all accounts use the same login password.
-	In addition, if you are using the proxy's `--cache-store` parameter you will need to manually remove unencrypted
-	secrets from this configuration file after the encrypted secret has been created (i.e., it will not be automatic).
+	to prevent access to it. However, when using the client credentials grant (CCG) flow or a service account, there is
+	no user involved, and possession of the secret grants full access to an account. If you use either of these methods
+	and it is possible that others may gain access to the proxy's configuration file; or, you are using catch-all
+	accounts (see below) and others may attempt to log in with accounts that the secret has access to but that you have
+	not yet set up with the proxy, set `encrypt_client_secret_on_first_use` to True and the proxy will replace the
+	`client_secret` value with a new property `client_secret_encrypted` at the next token refresh. Note that this option
+	is not fully compatible with `allow_catch_all_accounts` unless all accounts use the same login password, or you
+	undertake some additional manual setup configuration (see below for further details). In particular, if you are
+	using catch-all accounts or the proxy's `--cache-store` parameter you must manually remove unencrypted secrets from
+	the local configuration file after the encrypted secret has been created (i.e., this will not be automatic).
 
 	- allow_catch_all_accounts (default = False): The default behaviour of the proxy is to require a full separate
 	configuration file entry for each account. However, when proxying multiple accounts from the same domain it can be
@@ -225,9 +239,11 @@ documentation = The parameters below control advanced options for the proxy. In
 	example, add a section [@domain.com] with all of the standard required account values, and the proxy will intercept
 	authentication requests for all usernames at `domain.com`. Whenever a previously unseen account attempts to connect,
 	account authorisation will take place as normal, and the proxy will automatically create a new account-level section
-	that does not need to be configured manually. Any account-level configuration will override domain-level values.
-	If needed, the global catch-all section [@] can also be used. Please note that this option is not compatible with
-	`encrypt_client_secret_on_first_use` unless all IMAP/POP/SMTP accounts at the same domain use the same password.
+	that does not need to be configured manually. Any account-level configuration will override domain-level values
+	(except for account access and refresh tokens). If needed, the global catch-all section [@] can also be used. Please
+	note that this option is not fully compatible with `encrypt_client_secret_on_first_use` unless all IMAP/POP/SMTP
+	accounts at the same domain use the same password, or you undertake additional manual configuraton steps - see the
+	discussion at https://github.com/simonrob/email-oauth2-proxy/issues/214#issuecomment-1861593781 for details.
 
 [emailproxy]
 delete_account_token_on_password_error = True

emailproxy.py

@@ -6,7 +6,7 @@
 __author__ = 'Simon Robinson'
 __copyright__ = 'Copyright (c) 2023 Simon Robinson'
 __license__ = 'Apache 2.0'
-__version__ = '2023-11-19'  # ISO 8601 (YYYY-MM-DD)
+__version__ = '2023-12-20'  # ISO 8601 (YYYY-MM-DD)
 __package_version__ = '.'.join([str(int(i)) for i in __version__.split('-')])  # for pyproject.toml usage only
 
 import abc
@@ -799,7 +799,11 @@ def get_account_with_catch_all_fallback(option):
                         return False, '%s: Login failed for account %s: %s' % (APP_NAME, username, auth_result)
 
                 if not oauth2_flow:
-                    oauth2_flow = 'client_credentials'  # default to CCG over ROPCG if not set (ROPCG is `password`)
+                    Log.error('No `oauth2_flow` value specified for', username, '- aborting login')
+                    return (False, '%s: Incomplete config file entry found for account %s - please make sure an '
+                                   '`oauth2_flow` value is specified when using a method that does not require a '
+                                   '`permission_url`' % (APP_NAME, username))
+
                 response = OAuth2Helper.get_oauth2_authorisation_tokens(token_url, redirect_uri, client_id,
                                                                         client_secret, auth_result, oauth2_scope,
                                                                         oauth2_flow, username, password)
@@ -852,7 +856,11 @@ def get_account_with_catch_all_fallback(option):
             return OAuth2Helper.get_oauth2_credentials(username, password, reload_remote_accounts=False)
 
         except InvalidToken as e:
-            if AppConfig.get_global('delete_account_token_on_password_error', fallback=True):
+            # regardless of the `delete_account_token_on_password_error` setting, we only reset tokens for standard or
+            # ROPCG flows; when using CCG or a service account it is far safer to deny account access and require a
+            # config file edit in order to reset an account rather than allowing *any* password to be used for access
+            if AppConfig.get_global('delete_account_token_on_password_error', fallback=True) and (
+                    permission_url or oauth2_flow not in ['client_credentials', 'service_account']):
                 config.remove_option(username, 'access_token')
                 config.remove_option(username, 'access_token_expiry')
                 config.remove_option(username, 'token_salt')