-
Notifications
You must be signed in to change notification settings - Fork 0
/
HOWTO
311 lines (234 loc) · 9.26 KB
/
HOWTO
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
# SPDX-License-Identifier: GPL-3.0-or-later
# Copyright (C) 2019--2022 Junjiro R. Okajima
XOAUTH2-PIPE
HOWTO
Contents
1 Google API Console
2 Build and install
2.1 Alternative
3 Refresh-token per sender address
4 Unit test
5 Configure systemd and MTA
5.1 systemd
5.2 Exim
6 Final test
----------------------------------------
1 Google API Console
Obtain client-id and client-secret, and store them in xoauth2-client
file in the source tree.
(1) Go to https://console.developers.google.com.
(2) Login using any Gmail account.
(3) Create a new project called "xoauth2-pipe ".
(4) Enable "Gmail API".
(5) Create credentials.
Which API are you using? Gmail API
Where will you be calling the API from? Other UI
What data will you be accessing? User data
(6) Obtain client-id and client-secret and store them in
xoauth2-client file.
(7) Setup OAuth consent screen.
Application name xoauth2-pipe
(8) Add your gmail address to "test users".
2 Build and install
Some other commands or libraries are necessary such as
* curl(1) and libcurl(3)
* libmodpbase64(3)
* stunnel(1)
And simply run these commands.
----------------------------------------
$ make -j
$ make -n install install_user_file
$ sudo make install install_user_file
----------------------------------------
Note that even if you install xoauth2-pipe, it doesn't affect your MTA
and its mail delivery at all since you didn't configure MTA to use
xoauth2-pipe yet.
2.1 Alternative
There are several customizable make-variables. If you want, set them
manually.
* USER_FILE
The path of the file containing the user's refresh-token. The
default is /etc/xoauth2-user. The file should not be
world-readable, limited to the super-user and the special group for
MTA only (MTA_GROUP, see below).
* MTA_GROUP
The group of USER_FILE (above). The default is Debian-exim (since I
am a debian user). The group should match to your MTA's since
USER_FILE is read by MTA as a part of the mail delivery.
* SUPPORT_POP3
Decide whether to support POP3 or not. The default is 1 which means
to support.
Before configuring your MTA, you need a few more steps such as storing
user's refresh-token. Obviously you should test xoauth2-pipe locally
first when it is ready.
3 Refresh-token per sender address
(1) Run "xoauth2-rtoken <web_browser_command>".
It will invoke the specified web_browser_command which will lead you
to the screen where you should allow xoauth2-pipe to handle the
e-mail on Gmail account.
(2) As a result of allowing, the screen will show you a code called
"authorization code" which looks like "4/rQHMvehpxz9q... ".
(3) The tool xoauth2-rtoken is waiting for you to enter the
authorization code, so copy/paste the code and hit enter.
Then the tool will show you the refresh-token such like
"1//0eS2wvl9xyz... ".
(4) Manually copy/paste the refresh-token to the file USER_FILE
(/etc/xoauth2-user by default. From now on this document calls it
USER_FILE since the path may be changed when it was installed).
The file format is simple, just the account, colon, and the
refresh-token in a line.
----------------------------------------
[email protected]:1//0eS2wvl9xyz...
----------------------------------------
4 Unit test
Essentially the test is simulating an SMTP session.
(1) Decide a sender and a recipient.
The sender address should be Gmail address. The recipient address
can be anything as long as you can read the delivered mail. Here I
call them $sender and $recipient respectively.
(2) Run the test script called test.sh in the source tree.
----------------------------------------
$ sh ./test.sh stdalone $sender $recipient
----------------------------------------
By default, test.sh acquires a privilege to read USER_FILE which is
readable by a superuser and the member of MTA's group only. If your
system is not debian or you have specified the make-variable
USER_FILE_GROUP at installing, you need to give an environment
variable TEST_USER to the test script in order to read USER_FILE.
----------------------------------------
$ env TEST_USER=your_MTA_account sh ./test.sh stdalone \
$sender $recipient
----------------------------------------
5 Configure systemd and MTA
Here I chose Exim(v4) as MTA since I am a debian user. I hope it
doesn't matter and any MTA will work by changing the options slightly.
5.1 systemd
You might know about systemd more than me since I have less
experiences on it. The purpose is simple, just to listen(2) on a
local port and invoke xoauth2-pipe.
First, decide the local port number where listens. Here I assume it
as 10025.
(1) Create /etc/systemd/system/[email protected] file.
----------------------------------------
[Unit]
Description=smtps for gmail
[Service]
ExecStart=/usr/sbin/xoauth2-pipe.sh smtp
StandardInput=socket
----------------------------------------
(2) Create /etc/systemd/system/gmail-smtp.socket file.
----------------------------------------
[Unit]
Description=smtp socket for gmail smtps
[Socket]
ListenStream=127.0.0.1:10025
Accept=yes
[Install]
WantedBy=sockets.target
----------------------------------------
(3) Make it start.
----------------------------------------
$ sudo systemctl enable gmail-smtp.socket
$ sudo systemctl start gmail-smtp.socket
----------------------------------------
(4) Make it sure.
Use netstat(1) or ss(1) command and see that systemd opens the port
10025. And run telnet(1) to connect the port.
----------------------------------------
$ ss -lt | fgrep -w 10025
LISTEN 0 128 127.0.0.1:10025 *:*
$ telnet localhost 10025
Trying 127.0.0.1...
Connected to localhost.
Escape character is '?^]'?.
220 smtp.gmail.com ESMTP w134... - gsmtp
QUIT
221 2.0.0 closing connection w134... - gsmtp
Connection closed by foreign host.
----------------------------------------
Connecting localhost:10025 starts the SMTP session between
smtp.gmail.com:smtps and showing "220 smtp.gmail.com ESMTP ..." line
means the success. Type QUIT and end telnet(1) command.
Any other result means a failure.
5.2 Exim
The purpose is the "mail routing by the sender address". In other
words, when the domain part of the sender address is gmail.com, then
deliver the mail to localhost:10025 which is an entrance to
xoauth2-pipe.
(1) Add a router such like this in your Exim configuration file.
----------------------------------------
# routing by sender
gmail:
driver = manualroute
senders = *@gmail.com
domains = ! +local_domains
# xoauth2-pipe + stunnel
route_list = * localhost::10025
self = send
transport = remote_smtp
debug_print = "R: gmail, from=$h_from, sa=$sender_address"
----------------------------------------
Be careful to the order of the routers in the configuration file.
If your configuration is not changed from the default setting, I'd
suggest you to insert this router just after "hubbed_hosts".
(2) Load the new configuration.
----------------------------------------
$ sudo /etc/init.d/exim4 reload
----------------------------------------
(3) Test the routing.
----------------------------------------
$ sh ./test.sh exim $sender $recipient
+ /usr/sbin/exim -odf -v -f $sender $recipient
LOG: MAIN
<= $sender... U=$your_name P=local S=299
delivering 1iCblJ-00...
R: gmail, from= sa=$sender...
T: remote_smtp for $recipient...
Transport port=25 replaced by host-specific port=10025
Connecting to localhost [127.0.0.1]:10025... connected
SMTP<< 220 smtp.gmail.com ESMTP 207sm3... - gsmtp
SMTP>> EHLO $your_domain...
SMTP<< 250-smtp.gmail.com at your service, [nnn.nnn....]
250-SIZE 35882577
250-8BITMIME
250-AUTH LOGIN PLAIN XOAUTH2 PLAIN-CLIENTTOKEN OAUTHBEARER XOAUTH
250-ENHANCEDSTATUSCODES
250-PIPELINING
250-CHUNKING
250 SMTPUTF8
SMTP>> MAIL FROM:<$sender> SIZE=1330
SMTP>> RCPT TO:<$recipient>
SMTP>> DATA
SMTP<< 250 2.1.0 OK 207sm3... - gsmtp
SMTP<< 250 2.1.5 OK 207sm3... - gsmtp
SMTP<< 354 Go ahead 207sm3... - gsmtp
SMTP>> writing message and terminating "."
SMTP<< 250 2.0.0 OK 156... 207sm3... - gsmtp
SMTP>> QUIT
SMTP(close)>>
LOG: MAIN
=> $recipient R=gmail T=remote_smtp H=localhost [127.0.0.1] C="250
2.0.0 OK 156... 207sm3... - gsmtp"
LOG: MAIN
Completed
----------------------------------------
In the output, you can see these facts.
* The selected router is "gmail" which you added just now.
* The selected transport is "remote_smtp" and it connects to
localhost:10025.
* The first output in the SMTP session is a banner from Gmail.
* There is no AUTH command (but it is issued internally).
Needless to say, you should check all headers in the received test
mail thoroughly.
If you still allow "Less secure app access" on your Gmail account,
then disallow it and test again. Switching $sender and $recipient
may be a good test.
6 Final test
By the previous tests, I believe you are already confident that the
mail delivery is safe and sure. Let's try the final test which uses
the very basic ordinary mail(1) command.
(1) Disallow "Less secure app access" on your Gmail account.
(2) Run "sh ./test.sh mail $sender $recipient".
(3) Check all headers in the received mail.
Congratulations! You won!!