forked from simonrob/email-oauth2-proxy
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathemailproxy.config
156 lines (128 loc) · 9.55 KB
/
emailproxy.config
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
[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).
[Server setup]
documentation = Local servers are specified as demonstrated below where, for example, the section heading [IMAP-1993]
gives the type (which can be IMAP, POP or SMTP) and the local port number to listen on (i.e., 1993, etc). The local
port must be above 1023 (unless the proxy script is run via sudo), below 65536, and unique across local servers.
Multiple accounts can share the same server, however. Each server section must specify the `server_address` and
`server_port` of the remote server that it will be proxying - you can obtain these values from your email provider,
or use the details below for Office 365 and/or Gmail.
To allow the proxy to operate, your email client must be set up to use an unencrypted connection for IMAP/SMTP/POP
(i.e., no STARTTLS or SSL/TLS, just plain login credentials). The proxy will create a secure connection on your
behalf to the remote server from the outset by default (i.e., implicit SSL/TLS); see below if STARTTLS is required.
Server customisation:
- If your SMTP server uses the STARTTLS approach, add `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 STARTTLS and POP STARTTLS are not currently supported.
- If the property `local_address` is not specified, its value is assumed to be `localhost`. If required, this
parameter can be used to set an IP address or hostname for the proxy to listen on.
Advanced server configuration:
- In the standard configuration the channel between your email client and the proxy is unencrypted. This is not
normally of any concern since the proxy is typically a local-only service. However, if you prefer, you may provide
a `local_certificate_path` (e.g., /etc/letsencrypt/live/mail.example.net/fullchain.pem) and `local_key_path` (e.g.,
/etc/letsencrypt/live/mail.example.net/privkey.pem) for the server you are using the proxy with, and it will use
these to set up a secure connection between itself and your email client.
[IMAP-1993]
local_address = localhost
server_address = outlook.office365.com
server_port = 993
[POP-1995]
server_address = outlook.office365.com
server_port = 995
[SMTP-1587]
server_address = smtp.office365.com
server_port = 587
starttls = True
[IMAP-2993]
server_address = imap.gmail.com
server_port = 993
[POP-2995]
server_address = pop.gmail.com
server_port = 995
[SMTP-2465]
server_address = smtp.gmail.com
server_port = 465
[Account setup]
documentation = Accounts are specified using your email address as the section heading (e.g., [[email protected]],
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 `permission_url`, `token_url`, `oauth2_scope` and `redirect_uri`. If
you are adding an account for a service other than the examples shown below then the provider's documentation should
provide these details.
You will also need to add your own `client_id` and `client_secret` values as indicated below. These can either be
reused from an existing source (such as another email client that supports OAuth 2.0), or you can register and use
your own desktop app API client credentials. See https://developers.google.com/identity/protocols/oauth2/native-app
and the Microsoft link below for details. Multiple accounts on the same server can use the same values for the
`client_id` and `client_secret` properties; just duplicate these in each account's entry below. Note that there are
also example account configurations for AOL and Yahoo Mail below, but 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 in this configuration file, encrypted with the password you use in your email client. The password set in
your email client is not used for authentication (which is done separately via 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 password to avoid repeated re-authentication requests.
See the proxy's README.md file for more information and further configuration options.
Office 365 customisation:
- If your Office 365 configuration requires a tenant ID, place it in both `permission_url` and `token_url` in place
of `common` in the example below. For more detail about this, and guides for setting up your desktop app API client,
see the documentation at https://docs.microsoft.com/en-us/azure/active-directory/develop/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.
- It is possible to create Office 365 clients that do not require a secret to be sent. If this is the case for your
setup, delete the `client_secret` line from your account's configuration entry (do not leave the default value).
Advanced account configuration:
- For most configurations the default `redirect_uri` value of `http://localhost` is correct, but when using the
`--local-server-auth` proxy option you will need to either run the script via sudo (to use the implicit default port
80) or specify a different port (and/or a different host) - for example, `redirect_uri = http://localhost:8080`. In
addition, if you are using this proxy option in a configuration that is not directly exposed (such as a container or
private network) then you may also need to map `redirect_uri` traffic to 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 the `--local-server-auth`
option the proxy will start/stop a new local server for each authentication request, and does not explicitly handle
repeated requests or multiple accounts authenticating at the same using the same using the same redirect addresses.
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).
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.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/POP.AccessAsUser.All https://outlook.office365.com/SMTP.Send offline_access
redirect_uri = http://localhost
client_id = *** your client id here ***
client_secret = *** your client secret here ***
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 ***
permission_url = https://api.login.yahoo.com/oauth2/request_auth
token_url = https://api.login.yahoo.com/oauth2/get_token
oauth2_scope = mail-w
redirect_uri = http://localhost
client_id = *** your client id here ***
client_secret = *** your client secret here ***
permission_url = https://api.login.aol.com/oauth2/request_auth
token_url = https://api.login.aol.com/oauth2/get_token
oauth2_scope = mail-w
redirect_uri = http://localhost
client_id = *** your client id here ***
client_secret = *** your client secret here ***
[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. Set to False and the proxy will instead return an error when an incorrect password is provided.
[emailproxy]
delete_account_token_on_password_error = False