Add Google Cloud service account support (#224)

Authentication can now be handled via a Google Cloud service account

Author: simonrob

README.md

@@ -73,8 +73,9 @@ 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)
 - 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 also supports the [client credentials grant](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow) and [resource owner password credentials grant](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth-ropc) OAuth 2.0 flows if needed.
-Please note that currently only Office 365 is known to support these methods.
+The proxy supports [Google Cloud service accounts](https://cloud.google.com/iam/docs/service-account-overview) for access to Google Workspace Gmail.
+It also supports the [client credentials grant (CCG)](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow) and [resource owner password credentials grant (ROPCG)](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth-ropc) OAuth 2.0 flows.
+Please note that currently only Office 365 is known to support the CCG and ROPCG methods.
 See the [sample configuration file](https://github.com/simonrob/email-oauth2-proxy/blob/main/emailproxy.config) for further details.
 
 
@@ -213,7 +214,7 @@ You will know intervention is necessary if the proxy exits (rather than restarts
 To resolve this, exit the proxy and then run `launchctl load ~/Library/LaunchAgents/ac.robinson.email-oauth2-proxy.plist` from a terminal.
 A permission pop-up should appear requesting file access for python.
 Once this has been approved, the proxy's menu bar icon will appear as normal.
-In some cases — particularly when running the proxy in a virtual environment, or using the built-in macOS python, rather than the python.org version, or installations managed by, e.g., homebrew, pyenv, etc — the permission prompt does not appear.
+In some cases — particularly when running the proxy in a virtual environment, or using the built-in macOS python, rather than the python.org version, or installations managed by, e.g., homebrew, pyenv, etc. — the permission prompt does not appear.
 If this happens it is worth first trying to `unload` and then `load` the service via `launchctl`.
 If this still does not cause the prompt to appear, the only currently-known resolution is to run the proxy outside of a virtual environment and manually grant Full Disk Access to your python executable via the privacy settings in the macOS System Preferences.
 You may also need to edit the proxy's launch agent plist file, which is found at the location given in the command above, to set the path to your python executable – it must be the real path rather than a symlink (the `readlink` command can help here).
@@ -226,7 +227,7 @@ Please feel free to [open an issue](https://github.com/simonrob/email-oauth2-pro
 ## Advanced features<a id="advanced-features"></a>
 The [plugins variant](https://github.com/simonrob/email-oauth2-proxy/tree/plugins) has an additional feature that enables 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.
-For example, the [IMAPIgnoreSentMessageUpload plugin](https://github.com/simonrob/email-oauth2-proxy/blob/plugins/plugins/IMAPIgnoreSentMessageUpload.py) intercepts any client commands to add emails to the IMAP sent messages mailbox, which resolves message duplication issues for servers that automatically do this when emails are received via SMTP (e.g., Office 365, Gmail, etc).
+For example, the [IMAPIgnoreSentMessageUpload plugin](https://github.com/simonrob/email-oauth2-proxy/blob/plugins/plugins/IMAPIgnoreSentMessageUpload.py) intercepts any client commands to add emails to the IMAP sent messages mailbox, which resolves message duplication issues for servers that automatically do this when emails are received via SMTP (e.g., Office 365, Gmail, etc.).
 The [IMAPCleanO365ATPLinks plugin](https://github.com/simonrob/email-oauth2-proxy/blob/plugins/plugins/IMAPCleanO365ATPLinks.py) restores "Safe Links" modified by Microsoft Defender for Office 365 to their original URLs.
 The [SMTPBlackHole plugin](https://github.com/simonrob/email-oauth2-proxy/blob/plugins/plugins/SMTPBlackHole.py) gives the impression emails are being sent but actually silently discards them, which is useful for testing email sending tools.
 See the [documentation and examples](https://github.com/simonrob/email-oauth2-proxy/tree/plugins/plugins) for further details, additional sample plugins and setup instructions.
@@ -245,7 +246,7 @@ For Docker, blacktirion has an [example configuration](https://github.com/blackt
 
 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.
-There are also dedicated helpers available for specific applications (e.g., [mutt_oauth2](https://gitlab.com/muttmua/mutt/-/blob/master/contrib/mutt_oauth2.py)), and several open-source email clients that support OAuth 2.0 natively (e.g., [Thunderbird](https://www.thunderbird.net/), [Mailspring](https://getmailspring.com/), [FairEmail](https://email.faircode.eu/), [Evolution](https://wiki.gnome.org/Apps/Evolution), etc).
+There are also dedicated helpers available for specific applications (e.g., [mutt_oauth2](https://gitlab.com/muttmua/mutt/-/blob/master/contrib/mutt_oauth2.py)), and several open-source email clients that support OAuth 2.0 natively (e.g., [Thunderbird](https://www.thunderbird.net/), [Mailspring](https://getmailspring.com/), [FairEmail](https://email.faircode.eu/), [Evolution](https://wiki.gnome.org/Apps/Evolution), etc.).
 
 [DavMail](http://davmail.sourceforge.net/) is an alternative to this proxy that takes the same approach of providing a local IMAP/POP/SMTP server (and more) for Exchange/Office 365, though it does this by translating these protocols into Exchange API calls rather than proxying the connection.
 That approach is very useful in situations where server-side IMAP/POP/SMTP is not supported or enabled, or the full Exchange capabilities are needed, but it has limitations in terms of speed and the number of email messages that can be retrieved.

emailproxy.config

@@ -121,17 +121,36 @@ 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 for both methods towards the end of the sample
-	account entries below. 
+	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.
 
 		- 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.
+		already exists its configuration file). Using the CCG flow with the proxy in a publicly-accessible context is
+		not advised. 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.
+
+	Gmail customisation:
+	- The proxy supports the use of service accounts with Gmail for Google Workspace (note: normal Gmail accounts do not
+	support this method). To use this option, 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). Set
+	`oauth2_flow = service_account`. The service account key itself can either be referenced in an external file, or
+	pasted directly into the account entry. For the file approach, set `client_id = file` and `client_secret` to the
+	full path to the JSON key file. To include the key directly, set `client_id = key`, then paste the full contents of
+	your service account's JSON key as the value for `client_secret`, making sure all lines are indented by at least one
+	space (so that the proxy can tell they are all part of one value). An example is given for both methods towards the
+	end of the sample account entries below.
+
+		- WARNING: Please note that the same potential security issues outlined above with O365's CCG flow also apply to
+		the service account method: there is essentially no local access control when creating new accounts. Using a
+		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.
 
 	Advanced account configuration:
 	- For most configurations the default `redirect_uri` value of `http://localhost` is correct, unless you have
@@ -201,6 +220,25 @@ redirect_uri = http://localhost
 client_id = *** your client id here ***
 client_secret = *** your client secret here ***
 
+[[email protected]]
+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
+oauth2_scope = https://mail.google.com/
+oauth2_flow = service_account
+redirect_uri = http://localhost
+client_id = file
+client_secret = *** your /path/to/service-account-key.json here ***
+
+[[email protected]]
+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
+oauth2_scope = https://mail.google.com/
+oauth2_flow = service_account
+redirect_uri = http://localhost
+client_id = key
+client_secret = *** your pasted service account JSON key file contents here,
+	making sure to indent all lines by at least one space ***
+
 [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
@@ -215,7 +253,8 @@ documentation = The parameters below control advanced options for the proxy. In
 	be laborious or need administrator intervention, this can potentially result in a denial-of-service issue, whether
 	malicious or not. It can also be the source of confusion if using a client (such as Firefox) that stores a separate
 	password per protocol for each account, but does not make this clear when changing account passwords. Set this
-	option to False and the proxy will instead return an error when an incorrect password is provided.
+	option to False and the proxy will instead return an error when an incorrect password is provided. For accounts
+	using the O365 CCG flow or a Google Cloud service account this option will be overridden and always set to False.
 
 	- encrypt_client_secret_on_first_use (default = False): The proxy encrypts sensitive configuration values (e.g.,
 	cached access tokens) using the password that is given when accessing an account via IMAP/POP/SMTP. It does not do
@@ -242,7 +281,7 @@ documentation = The parameters below control advanced options for the proxy. In
 	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
+	accounts at the same domain use the same password, or you undertake additional manual configuration steps - see the
 	discussion at https://github.com/simonrob/email-oauth2-proxy/issues/214#issuecomment-1861593781 for details.
 
 [emailproxy]