Add support for resource owner password credentials grant flow (#89)

Closes #81

Author: simonrob

README.md

@@ -12,7 +12,7 @@ Email services that support IMAP, POP and/or SMTP access are increasingly requir
 - 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 run a server with multiple services 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 script can help. Follow the instructions below to get started, and please [open an issue](https://github.com/simonrob/email-oauth2-proxy/issues) with any problems or suggestions.
+In all of these cases and more, this proxy script can help. Follow the instructions below to get started, and please [open an issue](https://github.com/simonrob/email-oauth2-proxy/issues) with any problems or suggestions. For commercial support or feature requests, please also consider [sponsoring this project](https://github.com/sponsors/simonrob?frequency=one-time).
 
 
 ## Getting started
@@ -39,7 +39,7 @@ If you do not have access to credentials for an existing client you will need to
 - Gmail / Google Workspace: register a [Google API desktop app client](https://developers.google.com/identity/protocols/oauth2/native-app)
 - AOL and Yahoo Mail are not currently allowing new client registrations with the OAuth email scope – the only option here is to use the credentials from an existing client that does have this permission.
 
-The proxy also supports the [client credentials grant flow](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#use-client-credentials-grant-flow-to-authenticate-imap-and-pop-connections) if needed, though please note that Office 365 only supports IMAP/POP in this mode, and _not_ SMTP. See the [sample configuration file](emailproxy.config) for further details.
+The proxy also supports the [client credentials grant](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow) and [resource owner password credentials grant](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth-ropc) OAuth 2.0 flows if needed. Please note that currently only Office 365 is known to support these methods. In addition, when using the client credentials grant flow, Office 365 only supports IMAP/POP, [_not_ SMTP](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#use-client-credentials-grant-flow-to-authenticate-imap-and-pop-connections). See the [sample configuration file](emailproxy.config) for further details.
 
 
 ## Optional arguments and configuration
@@ -79,7 +79,7 @@ It is often helpful to be able to view the raw connection details when debugging
 ### Dependencies and setup
 On macOS the setup and installation instructions above should automatically install all required dependencies. Any error messages you may encounter (for example, with your `pip` version and `cryptograpy`, or `pillow` and `imagingft` dependencies, or [macOS SSL failures](https://github.com/simonrob/email-oauth2-proxy/issues/14#issuecomment-1077379254)) normally give clear explanations of the issues and point to instructions for resolving these problems. Please [open an issue](https://github.com/simonrob/email-oauth2-proxy/issues) if you encounter any other problems here.
 
-When first launching on Linux you may encounter errors similar to `Namespace […] not available`. 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 login windows. See the [pywebview dependencies](https://pywebview.flowrl.com/guide/installation.html#dependencies) page and [issue 1](https://github.com/simonrob/email-oauth2-proxy/issues/1#issuecomment-831746642) in this repository for a summary and suggestions about how to resolve this.
+When first launching on Linux you may encounter errors similar to `Namespace […] not available`, or issues with the task bar icon display. 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 login 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 [issue 1](https://github.com/simonrob/email-oauth2-proxy/issues/1#issuecomment-831746642) 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). If you are unable to resolve this by following the [pythonnet installation instructions](https://github.com/pythonnet/pythonnet/wiki/Installation), you may find that installing a [prebuilt wheel](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pythonnet) helps fix the issue. Note that the public releases of pythonnet can take some time to be compatible with the latest major python release, so it can be worth using a slightly older version of python, or a pre-release version of pythonnet. This should be handled by the proxy's `requirements.txt`, but see [issue 45](https://github.com/simonrob/email-oauth2-proxy/issues/45) for a workaround if needed.
 

emailproxy.config

@@ -97,30 +97,37 @@ documentation = Accounts are specified using your email address as the section h
 
 	- It is possible to create Office 365 clients that do not require a secret to be sent. If this is the case for your
 	setup, delete the `client_secret` line from your account's configuration entry (do not leave the default value).
-	
-	- If your Office 365 configuration uses the client credentials grant flow rather than interactive authentication,
-	add your account entry as normal, but do not add a `permission_url` value (it does not apply in this mode, and its
-	absence signals to the proxy to use the appropriate token retrieval mechanism). Please note that with the client
-	credentials grant flow SMTP is not supported, and by default there is essentially no local access control when using
-	IMAP/POP. To alleviate this, you are encouraged to enable client secret encryption in the proxy - see the setting 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 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.
+
+	- 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.
 
 	Advanced account configuration:
 	- For most configurations the default `redirect_uri` value of `http://localhost` is correct, unless you have
 	explicitly set your OAuth 2.0 client to use a different address here (which you will need to manually redirect to
-	the proxy). Please also note that this address is `http` and not `https` (which is not supported). When using the
-	`--local-server-auth` proxy option you will need to either run the script via sudo (to use the implicit default port
-	80) or specify a different port (and/or a different host) - for example, `redirect_uri = http://localhost:8080`. In
-	addition, if you are using this proxy option in a configuration that is not directly exposed (such as a container or
-	private network) then you may also need to map `redirect_uri` traffic to a private address. Once this is configured
-	(via external tools/rules), instruct the proxy to listen here using the parameter `redirect_listen_address` - for
-	example, `redirect_listen_address = http://10.0.0.0:8080`. Please note that when using the `--local-server-auth`
-	option the proxy will start/stop a new local server for each authentication request, and does not explicitly handle
-	repeated requests or multiple accounts authenticating at the same using the same using the same redirect addresses.
-	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).
+	the proxy). Please also note that this address is `http` and not `https` (which is not supported unless you provide
+	a secure connection yourself outside of the proxy using an external tool).
+	
+	- When using the `--local-server-auth` option you will need to either run the proxy with additional privileges to
+	use the implicit default port 80 (e.g., via sudo) or specify a different port (and/or a different host if needed) -
+	for example, `redirect_uri = http://localhost:8080`. In addition, if you are using this proxy option in a setup that
+	is not directly exposed (such as a container or private network) you may also need to map `redirect_uri` traffic via
+	a private address. Once this is configured (via external tools/rules), instruct the proxy to listen here using the
+	parameter `redirect_listen_address` - for example, `redirect_listen_address = http://10.0.0.0:8080`.
+	
+	- Please note that when using `--local-server-auth` the proxy will start/stop a new local server for each incoming
+	authentication request, and does not explicitly handle repeated requests or multiple accounts authenticating using
+	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.
 
 [[email protected]]
 permission_url = https://login.microsoftonline.com/common/oauth2/v2.0/authorize
@@ -154,6 +161,13 @@ redirect_uri = http://localhost
 client_id = *** your client id here ***
 client_secret = *** your client secret here ***
 
+[[email protected]]
+token_url = https://login.microsoftonline.com/*** your tenant id here ***/oauth2/v2.0/token
+oauth2_scope = https://outlook.office365.com/.default
+oauth2_flow = client_credentials
+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