@@ -15,23 +15,23 @@ documentation = Local servers are specified as demonstrated below where, for exa
15
15
Multiple accounts can share the same server, however. Each server section must specify the `server_address` and
16
16
`server_port` of the remote server that it will be proxying - you can obtain these values from your email provider,
17
17
or use the details below for Office 365 and/or Gmail.
18
-
18
+
19
19
To allow the proxy to operate, your email client must be set up to use an unencrypted connection for IMAP/SMTP/POP
20
20
(i.e., no STARTTLS or SSL/TLS, just plain login credentials). The proxy will create a secure connection on your
21
21
behalf to the remote server from the outset by default (i.e., implicit SSL/TLS); see below if STARTTLS is required.
22
-
22
+
23
23
Server customisation:
24
24
- If your SMTP server uses the STARTTLS approach, add `starttls = True`, as shown in the [SMTP-1587] example below
25
25
(assumed to be False otherwise). With this parameter set, STARTTLS negotiation will be handled by the proxy on your
26
26
behalf (i.e., do not enable STARTTLS in your client). IMAP STARTTLS and POP STARTTLS are not currently supported.
27
-
27
+
28
28
- The `local_address` property can be used to set an IP address or hostname for the proxy to listen on. Both IPv4
29
29
and IPv6 are supported. If not specified, this value is set to `::` (i.e., dual-stack IPv4/IPv6 on all interfaces).
30
30
When a hostname is set the proxy will first resolve this to an IP address, preferring IPv6 over IPv4 if both are
31
31
available. When running in an IPv6 environment with dual-stack support, the proxy will attempt to listen on both
32
32
IPv4 and IPv6 hosts simultaneously. Note that tools such as `netstat` do not always accurately show dual-stack mode;
33
33
if you are having trouble connecting to the proxy, it is worth actually testing both IPv4 and IPv6 connections.
34
-
34
+
35
35
Advanced server configuration:
36
36
- In the standard configuration the channel between your email client and the proxy is unencrypted. This is not
37
37
normally of any concern since the proxy is typically a local-only service. However, if you prefer, you may provide
@@ -77,7 +77,7 @@ documentation = Accounts are specified using your email address as the section h
77
77
Each account section must provide values for `permission_url`, `token_url`, `oauth2_scope` and `redirect_uri`. If
78
78
you are adding an account for a service other than the examples shown below then the provider's documentation should
79
79
provide these details.
80
-
80
+
81
81
You will also need to add your own `client_id` and `client_secret` values as indicated below. These can either be
82
82
reused from an existing source (such as another email client that supports OAuth 2.0), or you can register and use
83
83
your own desktop app API client credentials. See https://developers.google.com/identity/protocols/oauth2/native-app
@@ -86,38 +86,38 @@ documentation = Accounts are specified using your email address as the section h
86
86
`allow_catch_all_accounts` option. Note that while there are example account configurations for AOL and Yahoo Mail
87
87
below, these services are not currently accepting new OAuth 2.0 client registrations with the mail access scope, so
88
88
reusing existing credentials is the only option here.
89
-
89
+
90
90
Once the proxy is correctly configured, after the first successful use of an account its access token details will
91
91
be cached for future use, encrypted with the IMAP/POP/SMTP password you used in your email client. By default this
92
92
configuration file is reused for caching (so it must be writable), but you can specify a different location or
93
93
method using the proxy's `--cache-store` parameter. You should not add or edit cached values manually (i.e.,
94
94
`token_salt`, `access_token`, `access_token_expiry`, `refresh_token` and `last_activity`); the proxy handles this.
95
-
95
+
96
96
The password used in your email client is not used for authentication with the actual email server (this is done via
97
97
OAuth 2.0 in a web browser), so it can be different to your real account password, which is helpful for debugging.
98
98
Please note, though, that all clients that use a particular account via the proxy should use the same IMAP/POP/SMTP
99
99
password to avoid repeated re-authentication requests (which is the proxy's default behaviour when credential
100
100
decryption fails). See the proxy's README.md file for more information and the end of this file for further options.
101
-
101
+
102
102
Office 365 customisation:
103
103
- Unlike other providers, Office 365 requires an OAuth 2.0 scope that explicitly specifies `offline_access` (shown
104
104
in the example below) in order to allow the proxy to refresh its access token on your behalf. The proxy will still
105
105
work if this parameter is not included, but you will need to re-authenticate extremely often (about once per hour).
106
-
106
+
107
107
- By default, new Entra (Azure AD) clients are accessible only within your own tenant. If you are registering a new
108
108
client to use with the proxy (and do not want to make it available outside your own organisation) you will need to
109
109
replace `common` with your tenant ID in the Office 365 `permission_url` and `token_url` values below. Alternatively,
110
110
you can reuse credentials from an existing client registration (see the proxy's README.md file), or configure your
111
111
client as a multi-tenant application. For more detail about this, and guides for setting up your desktop app client,
112
112
see the documentation at https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app.
113
-
113
+
114
114
- Office 365 shared mailboxes are supported: add an account entry here using the email address of the shared
115
115
mailbox as the account name. When asked to authenticate, log in as the user that access has been delegated to.
116
116
Note that Office 365 no-longer supports the `authorised.user@example.com/delegated.mailbox` username syntax here.
117
-
117
+
118
118
- It is possible to create Office 365 clients that do not require a secret to be sent. If this is the case for your
119
119
setup, delete the `client_secret` line from your account's configuration entry (do not leave the default value).
120
-
120
+
121
121
- The proxy supports the client credentials grant (CCG) and resource owner password credentials grant (ROPCG) OAuth
122
122
2.0 flows (both currently only known to be available for Office 365). To use either of these flows, add an account
123
123
entry as normal, but do not add a `permission_url` value (it does not apply, and its absence signals to the proxy to
@@ -130,20 +130,20 @@ documentation = Accounts are specified using your email address as the section h
130
130
of this file. In addition, if you are using the proxy in an environment where there is any possibility of malicious
131
131
access attempts before the first valid login then pre-encrypting account entries is highly recommended - see the
132
132
example setup script at https://github.com/simonrob/email-oauth2-proxy/issues/61#issuecomment-1259110336.
133
-
133
+
134
134
Advanced account configuration:
135
135
- For most configurations the default `redirect_uri` value of `http://localhost` is correct, unless you have
136
136
explicitly set your OAuth 2.0 client to use a different address here (which you will need to manually redirect to
137
137
the proxy). Please also note that this address is `http` and not `https` (which is not supported unless you provide
138
138
a secure connection yourself outside of the proxy using an external tool).
139
-
139
+
140
140
- When using the `--local-server-auth` option you will need to either run the proxy with additional privileges to
141
141
use the implicit default port 80 (e.g., via sudo) or specify a different port (and/or a different host if needed) -
142
142
for example, `redirect_uri = http://localhost:8080`. In addition, if you are using this proxy option in a setup that
143
143
is not directly exposed (such as a container or private network) you may also need to map `redirect_uri` traffic via
144
144
a private address. Once this is configured (via external tools/rules), instruct the proxy to listen here using the
145
145
parameter `redirect_listen_address` - for example, `redirect_listen_address = http://10.0.0.0:8080`.
146
-
146
+
147
147
- Please note that when using `--local-server-auth` the proxy will start/stop a new local server for each incoming
148
148
authentication request, and does not explicitly handle repeated requests or multiple accounts authenticating using
149
149
the same address. To avoid clashes, it is recommended that each account has a unique `redirect_uri` (or
@@ -194,7 +194,7 @@ client_secret = *** your client secret here ***
194
194
documentation = The parameters below control advanced options for the proxy. In most cases you will not need to modify
195
195
the values in this section. If any of these values are not found, the proxy will assume the default value, which
196
196
can be found in the example config file (https://github.com/simonrob/email-oauth2-proxy/blob/main/emailproxy.config)
197
-
197
+
198
198
Parameter documentation:
199
199
- delete_account_token_on_password_error (default = True): Once an account has been authenticated via the proxy, if
200
200
there is a login attempt with a different (local) password, its default behaviour is to remove the saved OAuth 2.0
@@ -205,7 +205,7 @@ documentation = The parameters below control advanced options for the proxy. In
205
205
malicious or not. It can also be the source of confusion if using a client (such as Firefox) that stores a separate
206
206
password per protocol for each account, but does not make this clear when changing account passwords. Set this
207
207
option to False and the proxy will instead return an error when an incorrect password is provided.
208
-
208
+
209
209
- encrypt_client_secret_on_first_use (default = False): The proxy encrypts sensitive configuration values (e.g.,
210
210
cached access tokens) using the password that is given when accessing an account via IMAP/POP/SMTP. It does not do
211
211
this for values that are not sensitive. In the most common operation mode (i.e., interactively authorising account
@@ -217,7 +217,7 @@ documentation = The parameters below control advanced options for the proxy. In
217
217
that this option is not compatible with `allow_catch_all_accounts` unless all accounts use the same login password.
218
218
In addition, if you are using the proxy's `--cache-store` parameter you will need to manually remove unencrypted
219
219
secrets from this configuration file after the encrypted secret has been created (i.e., it will not be automatic).
220
-
220
+
221
221
- allow_catch_all_accounts (default = False): The default behaviour of the proxy is to require a full separate
222
222
configuration file entry for each account. However, when proxying multiple accounts from the same domain it can be
223
223
cumbersome to have to create multiple near-identical configuration profiles. To simplify this the proxy supports
0 commit comments