emailproxy.config

[Email OAuth 2.0 Proxy configuration file]
documentation = This is a sample Email OAuth 2.0 Proxy configuration file. Configure the proxy by adding items in the
	[Server setup] and [Account setup] sections below. You may delete any servers or accounts that you do not intend to
	use. Documentation is provided inline, with example setups for Gmail and Office 365 (though you will need to enter
	your own desktop app API client credentials in the accounts section). Use the `Reload configuration file` menu
	option or send a SIGHUP signal (or quit the proxy before editing, then restart) to apply any changes.
format = This file's format is documented at docs.python.org/library/configparser#supported-ini-file-structure. Values
	that span multiple lines should be indented deeper than the first line of their key (as in this comment). Quoting
	of values is not required. Documentation sections can be removed if needed (though it is advisable to leave these
	in place for reference) - thw only required sections are the individual server and account items of your setup.
warning = Do not commit changes to this file into a public repository (e.g., GitHub, etc). While the proxy encrypts the
	OAuth 2.0 tokens it obtains and saves on your behalf, it cannot protect these against offline brute-force attacks.


[Server setup]
documentation = Local servers are specified as demonstrated below where, for example, the section heading [IMAP-1993]
	gives the type (which can be IMAP, POP or SMTP) and the local port number to listen on (i.e., 1993, etc). The local
	port must be above 1023 (unless the proxy script is run via sudo), below 65536, and unique across local servers.
	Multiple accounts can share the same server, however. Each server section must specify the `server_address` and
	`server_port` of the remote server that it will be proxying - you can obtain these values from your email provider,
	or use the details below for Office 365 and/or Gmail.

	To allow the proxy to operate, your email client must be set up to use an unencrypted connection for IMAP/SMTP/POP
	(i.e., no STARTTLS or SSL/TLS, just plain login credentials). The proxy will create a secure connection on your
	behalf to the remote server from the outset by default (i.e., implicit SSL/TLS); see below if STARTTLS is required.

	Server customisation:
	- If your SMTP server uses the STARTTLS approach, add `server_starttls = True`, as shown in the [SMTP-1587] example
	below (assumed to be False otherwise). With this parameter set, STARTTLS negotiation will be handled by the proxy
	on your behalf (i.e., do not enable STARTTLS in your client). IMAP/POP STARTTLS are not currently supported.

	- The `local_address` property can be used to set an IP address or hostname for the proxy to listen on. Both IPv4
	and IPv6 are supported. If not specified, this value is set to `::` (i.e., dual-stack IPv4/IPv6 on all interfaces).
	When a hostname is set the proxy will first resolve this to an IP address, preferring IPv6 over IPv4 if both are
	available. When running in an IPv6 environment with dual-stack support, the proxy will attempt to listen on both
	IPv4 and IPv6 hosts simultaneously. Note that tools such as `netstat` do not always accurately show dual-stack mode;
	if you are having trouble connecting to the proxy, it is worth actually testing both IPv4 and IPv6 connections.

	Advanced server configuration:
	- As explained above, you should not enable STARTTLS in your local client, as the proxy handles secure communication
	with the server on your behalf. However, if your client does not allow STARTTLS to be disabled, you can in addition
	set `local_starttls = True` to emulate STARTTLS locally to allow your client to connect. If you set this parameter,
	you must also provide a local certificate as outlined below.

	- In the standard configuration the channel between your email client and the proxy is unencrypted. This is not
	normally of any concern since the proxy is typically a local-only service. However, if you prefer, you may provide
	a `local_certificate_path` (e.g., /etc/letsencrypt/live/mail.example.net/fullchain.pem) and `local_key_path` (e.g.,
	/etc/letsencrypt/live/mail.example.net/privkey.pem) for the server you are using the proxy with, and it will use
	these to set up a secure connection between itself and your email client.

[IMAP-1993]
server_address = outlook.office365.com
server_port = 993
local_address = 127.0.0.1

[POP-1995]
server_address = outlook.office365.com
server_port = 995
local_address = 127.0.0.1

[SMTP-1587]
server_address = smtp-mail.outlook.com
server_port = 587
server_starttls = True
local_address = 127.0.0.1

[IMAP-2993]
server_address = imap.gmail.com
server_port = 993
local_address = 127.0.0.1

[POP-2995]
server_address = pop.gmail.com
server_port = 995
local_address = 127.0.0.1

[SMTP-2465]
server_address = smtp.gmail.com
server_port = 465
local_address = 127.0.0.1


[Account setup]
documentation = Accounts are specified using your email address as the section heading (e.g., [your.email@gmail.com],
	etc, below). Account usernames (i.e., email addresses) must be unique - only one entry per account is permitted.
	Each account section must provide values for at least `token_url`, `oauth2_scope` and `client_id`. Depending on the
	OAuth 2.0 flow you are using, other values may also be required (see examples below). If you are adding an account
	for a service other than the examples shown below then the provider's documentation should provide these details.

	You will also need to add your own `client_id` and `client_secret` values as indicated below. These can either be
	reused from an existing source (such as another email client that supports OAuth 2.0), or you can register and use
	your own desktop app API client credentials. See https://developers.google.com/identity/protocols/oauth2/native-app
	and the Microsoft link below for details. Multiple accounts on the same server can use the same values for the
	`client_id` and `client_secret` properties; just duplicate these in each account's entry below, or see the advanced
	`allow_catch_all_accounts` option. Note that while there are example account configurations for AOL and Yahoo Mail
	below, these services are not currently accepting new OAuth 2.0 client registrations with the mail access scope, so
	reusing existing credentials is the only option here.

	Once the proxy is correctly configured, after the first successful use of an account its access token details will
	be cached for future use, encrypted with the IMAP/POP/SMTP password you used in your email client. By default this
	configuration file is reused for caching (so it must be writable), but you can specify a different location or
	method using the proxy's `--cache-store` parameter. You should not add or edit cached values manually (i.e.,
	`token_salt`, `access_token`, `access_token_expiry`, `refresh_token` and `last_activity`); the proxy handles this.

	The password used in your email client is not used for authentication with the actual email server (this is done via
	OAuth 2.0 in a web browser), so it can be different to your real account password, which is helpful for debugging.
	Please note, though, that all clients that use a particular account via the proxy should use the same IMAP/POP/SMTP
	password to avoid repeated re-authentication requests (which is the proxy's default behaviour when credential
	decryption fails). See the proxy's README.md file for more information and the end of this file for further options.

	Office 365 customisation:
	- Unlike other providers, Office 365 requires an OAuth 2.0 scope that explicitly specifies `offline_access` (shown
	in the example below) in order to allow the proxy to refresh its access token on your behalf. The proxy will still
	work if this parameter is not included, but you will need to re-authenticate extremely often (about once per hour).

	- The example Office 365 configuration entries below use an OAuth 2.0 scope that clearly specifies IMAP, POP and
	SMTP permission. If you do not require one or more of these protocols, you may remove the relevant values to ensure
	the access tokens obtained on your behalf are as precisely-targeted as possible. Conversely, it is also possible to
	replace these specific scopes with the more generic `https://outlook.office365.com/.default`. Switching to a broader
	scope value may also be needed if you are using a version of O365 delivered by a regional provider (e.g., 21Vianet).
	See: https://github.com/simonrob/email-oauth2-proxy/issues/255 for more details and discussion.

	- By default, new Entra (Azure AD) clients are accessible only within your own tenant. If you are registering a new
	client to use with the proxy (and do not want to make it available outside your own organisation) you will need to
	replace `common` with your tenant ID in the Office 365 `permission_url` and `token_url` values below. Alternatively,
	you can reuse credentials from an existing client registration (see the proxy's README.md file), or configure your
	client as a multi-tenant application. For more detail about this, and guides for setting up your desktop app client,
	see the documentation at https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app.

	- Office 365 shared mailboxes are supported: add an account entry here using the email address of the shared
	mailbox as the account name. When asked to authenticate, log in as the user that access has been delegated to.
	Note that Office 365 no-longer supports the `authorised.user@example.com/delegated.mailbox` username syntax here.

	- 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).

	- To use O365 certificate credentials instead of a client secret, delete the `client_secret` line and instead
	provide a `jwt_certificate_path` (e.g., /path/to/certificate.pem) and `jwt_key_path` (e.g., /path/to/key.pem).
	Further documentation and examples can be found at https://github.com/simonrob/email-oauth2-proxy/pull/247.

	- 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). 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). 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. A sample pre-encryption script is provided for reference at
		https://github.com/simonrob/email-oauth2-proxy/issues/212#issuecomment-1867557029

	Advanced account configuration:
	- For most configurations the default `redirect_uri` value of `http://localhost` is correct, unless you have
	explicitly set the OAuth 2.0 client configuration with your provider to use a different address for this purpose
	(e.g., redirecting via an external domain). If this is the case, you will need to manually redirect this to the
	proxy. Please note that in most cases the address is indeed `http://localhost`, not `https`.

	- 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.

[your.office365.address@example.com]
permission_url = https://login.microsoftonline.com/common/oauth2/v2.0/authorize
token_url = https://login.microsoftonline.com/common/oauth2/v2.0/token
oauth2_scope = https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/POP.AccessAsUser.All https://outlook.office.com/SMTP.Send offline_access
redirect_uri = http://localhost
client_id = *** your client id here ***
client_secret = *** your client secret here ***

[your.email@gmail.com]
permission_url = https://accounts.google.com/o/oauth2/auth
token_url = https://oauth2.googleapis.com/token
oauth2_scope = https://mail.google.com/
redirect_uri = http://localhost
client_id = *** your client id here ***
client_secret = *** your client secret here ***

[your.email@yahoo.co.uk]
permission_url = https://api.login.yahoo.com/oauth2/request_auth
token_url = https://api.login.yahoo.com/oauth2/get_token
oauth2_scope = mail-w
redirect_uri = http://localhost
client_id = *** your client id here ***
client_secret = *** your client secret here ***

[your.email@aol.com]
permission_url = https://api.login.aol.com/oauth2/request_auth
token_url = https://api.login.aol.com/oauth2/get_token
oauth2_scope = mail-w
redirect_uri = http://localhost
client_id = *** your client id here ***
client_secret = *** your client secret here ***

[ccg.flow.configured.address@your-tenant.com]
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
oauth2_flow = client_credentials
client_id = *** your client id here ***
client_secret = *** your client secret here ***

[ropcg.flow.configured.address@your-tenant.com]
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
client_id = *** your client id here ***
client_secret = *** your client secret here ***

[service.account.accessible.address@your-domain.com]
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
client_id = file
client_secret = *** your /path/to/service-account-key.json here ***

[service.account.accessible.address@your-domain.org]
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
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
	can be found in the example config file (https://github.com/simonrob/email-oauth2-proxy/blob/main/emailproxy.config)

	Parameter documentation:
	- delete_account_token_on_password_error (default = True): Once an account has been authenticated via the proxy, if
	there is a login attempt with a different (local) password, its default behaviour is to remove the saved OAuth 2.0
	credentials and present a new authentication request. This is a sensible default for local use as it means that a
	password typo does not give the false impression that the proxy has somehow made the account inaccessible. However,
	if the proxy is used in a headless (often also public-facing) context, where authentication flows are more likely to
	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. 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
	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 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).

	- use_login_password_as_client_credentials_secret (default = False): When using the O365 client credentials grant
	(CCG) flow, rather than encrypting the client secret (see above), the proxy can be instructed to use the given
	IMAP/POP/SMTP login password as the client secret. This approach removes the risk of storing the unencrypted client
	secret in the proxy's configuration file, and also means there is no risk of unauthorised account access when using
	the O365 CCG flow in conjunction with the proxy's catch-all mode (see below). To enable this option, set
	`use_login_password_as_client_credentials_secret` to True. Note that if a `client_secret` value is present in your
	account's configuration entry, that value will be used instead of the given IMAP/POP/SMTP login password even if
	this option is enabled. To avoid this, remove the entire `client_secret` line from the configuration entry.

	- 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
	cumbersome to have to create multiple near-identical configuration profiles. To simplify this the proxy supports
	catch-all accounts when this option is set to True. Domain-level accounts are configured using section headings. For
	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
	(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 configuration 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
encrypt_client_secret_on_first_use = False
use_login_password_as_client_credentials_secret = False
allow_catch_all_accounts = False