[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 work 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