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 (examples are given for Office 365 / Outlook and 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.

	Advanced feature - proxy plugins:
	- Plugins are an advanced feature that enable 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. For more details
	about how to install and enable this feature, see the additional documentation and range of sample plugins explained
	at https://github.com/simonrob/email-oauth2-proxy/tree/plugins/plugins#email-oauth-20-proxy-plugins

[IMAP-1993]
documentation = *** note: this server will work for both Office 365 and personal Outlook/Hotmail accounts ***
server_address = outlook.office365.com
server_port = 993
local_address = 127.0.0.1

[POP-1995]
documentation = *** note: this server will work for both Office 365 and personal Outlook/Hotmail accounts ***
server_address = outlook.office365.com
server_port = 995
local_address = 127.0.0.1

[SMTP-1587]
documentation = *** note: this server will work for both Office 365 and personal Outlook/Hotmail accounts ***
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 (in many cases) `client_secret` values as indicated below. These
	can either be reused from an existing source (such as an email client that supports OAuth 2.0), or you can register
	your own desktop app 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. See below for advanced use of this option to integrate with a
	secrets manager service. You should not add or edit cached values manually (i.e.,`token_salt`, `token_iterations`,
	`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 / Outlook customisation:
	- Unlike other providers, Office 365 / Outlook requires an OAuth 2.0 scope that explicitly grants `offline_access`
	(shown in the examples below) in order to allow the proxy to refresh its access token on your behalf. The proxy will
	still without this parameter, but you will need to re-authenticate extremely often (about once per hour).

	- The example Office 365 / Outlook 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 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 Microsoft services 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 `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.

	- It is possible to create Office 365 / Outlook OAuth 2.0 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 Office 365 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).
	If you are using Microsoft services delivered by a regional provider (such as 21Vianet) that uses a non-standard
	ROPCG variant, remove the `oauth2_scope` value and instead use `oauth2_resource`. Examples are given for each of
	these cases 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 in 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.

	- The proxy supports the device authorisation grant (DAG) OAuth 2.0 flow (currently only known to be available for
	Office 365 / Outlook), which may better suit headless systems. To use this flow, set `oauth2_flow = device`. With
	this flow, the proxy receives authorisation responses directly from the service provider, so no `redirect_uri` is
	needed. An example account configuration is given below. For additional customisation, the proxy modifications and
	scripts demonstrated at https://github.com/simonrob/email-oauth2-proxy/pull/317 show how the DAG flow authorisation
	message could be pushed to a separate device, which may be useful when running the proxy headless or without a GUI.

	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. Note that when creating the account entry here and when logging in from an
	email client, the username you should use is the account you are trying to access, not the service account user
	(i.e., do not use the auto-generated address that is similar to `your-user@your-project.iam.gserviceaccount.com`).

		- 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://`, 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.

	- When using the authorisation code OAuth 2.0 flow (which is the proxy's default), some providers require the use of
	a SHA-256 Proof Key for Code Exchange (PKCE) challenge instead of (or in addition to) a client secret. To use this
	method, set `use_pkce = True` as shown in the Fastmail example below. This value is ignored in all other flows.

	Integration with a secrets manager:
	- The proxy caches authenticated OAuth 2.0 tokens and associated metadata back into this configuration file by
	default, but can alternatively be configured to use either a separate local file (via `--cache-store /path/to/file`)
	or a secrets manager service for remote token storage. Currently only AWS Secrets Manager is supported. To use this
	feature, set the proxy's `--cache-store` parameter to either a full AWS ARN or a secret name, prefixing the value
	with `aws:` to identify its type to the proxy. If not already present, you must also install the AWS SDK for Python
	(`python -m pip install boto3`) and set up authentication credentials (including a region) - see the documentation
	at https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration. The minimum required
	permissions for the associated AWS IAM user are `secretsmanager:GetSecretValue` and `secretsmanager:PutSecretValue`.
	If the named AWS Secret does not yet exist, the proxy will attempt to create it; in this case, the permission
	`secretsmanager:CreateSecret` is also required.

[your.office365.or.outlook.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 (remove this entire line if a secret is not required) ***

[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@fastmail.com]
permission_url = https://api.fastmail.com/oauth/authorize
token_url = https://api.fastmail.com/oauth/refresh
oauth2_scope = https://www.fastmail.com/dev/protocol-imap https://www.fastmail.com/dev/protocol-pop https://www.fastmail.com/dev/protocol-smtp
client_id = *** your client id here ***
use_pkce = True

[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 - note that as new client registrations are not permitted for Yahoo, you will need to reuse an existing client ID (see the proxy's readme) ***
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 - note that as new client registrations are not permitted for AOL, you will need to reuse an existing client ID (see the proxy's readme) ***
client_secret = *** your client secret here ***

[dag.flow.configured.address@outlook.com]
permission_url = https://login.microsoftonline.com/common/oauth2/v2.0/devicecode
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
oauth2_flow = device
client_id = *** your client id here ***
client_secret = *** your client secret here (remove this entire line if a secret is not required) ***

[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 (remove this entire line if a secret is not required) ***

[ropcg.flow.scope.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 (remove this entire line if a secret is not required) ***

[ropcg.flow.resource.configured.address@your-tenant.com]
documentation = *** note: this is an advanced O365 account example specific to providers that use a non-standard version of the ROPCG flow (such as 21Vianet); in most cases you want the version above instead ***
token_url = https://login.partner.microsoftonline.cn/*** your tenant id here ***/oauth2/token
oauth2_resource = https://partner.outlook.cn
oauth2_flow = password
client_id = *** your client id here ***
client_secret = *** your client secret here (remove this entire line if a secret is not required) ***

[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