Showing content from https://github.com/simonrob/email-oauth2-proxy/raw/main/emailproxy.config below:
[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
RetroSearch is an open source project built by @garambo
| Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4