summaryrefslogtreecommitdiff
path: root/articles/pam-tfa.html
diff options
context:
space:
mode:
Diffstat (limited to 'articles/pam-tfa.html')
-rw-r--r--articles/pam-tfa.html157
1 files changed, 157 insertions, 0 deletions
diff --git a/articles/pam-tfa.html b/articles/pam-tfa.html
new file mode 100644
index 0000000..7bdc551
--- /dev/null
+++ b/articles/pam-tfa.html
@@ -0,0 +1,157 @@
1<!DOCTYPE html>
2<html lang=en>
3 <head>
4 <title></title>
5 <meta charset="utf-8"/>
6 <link rel="shortcut icon" href="favicon.ico"/>
7 <link rel='stylesheet' href='../style.css'/>
8 <meta name="viewport" content="width=device-width, initial-scale=1">
9 </head>
10<body>
11 <header><h1>PAM OATH Two Factor Authentication</h1></header>
12 <main>
13 <p>In this article we are going to look at configuring two factor
14 authentication via PAM using OATH. This is a simple and private way
15 to increase the security of your systems. Even if you are not familiar
16 with the term, it is likely that you
17 have used OATH before. OATH (specifically TOTP) is the rotating 6
18 digit code that you get from scanning a QR code when setting up 2FA
19 on an account.</p>
20
21 <p>This example will show how to configure 2FA for SSH logins to a
22 server, but can easily be generalized to cover other programs or
23 even all authentication on a system. The two factors here will be
24 public key authentication and then the OATH/TOTP code.
25 <em>It is highly recommended that you remain SSHd into your server
26 until after testing to avoid locking yourself out in the event
27 of a configuration error.</em></p>
28
29 <h2>Install Packages</h2>
30 <p>You only need to install a single package on the server side.</p>
31
32 <pre><code>apt install libpam-oath</code></pre>
33
34 <p>On the client machine that will be SSHing to the server install
35 these two packages.</p>
36
37 <pre><code>apt install oathtool qrencode</code></pre>
38
39 <h2>Configure OATH</h2>
40 <p>Create the OATH configuration file <strong>/etc/users.oath</strong>.
41 This file will contain the OATH secret keys so permissions need to be
42 set to only allow the root user to view it.</p>
43
44 <pre><code>touch /etc/users.oath
45chown root: /etc/users.oath
46chmod 600 /etc/users.oath</code></pre>
47
48 <p>Generate a secret key for the TOTP. Treat this secret key as you
49 would your SSH or GPG private key. Anyone who has this key will be able
50 to generate the code needed to authenticate.</p>
51
52 <pre><code>openssl rand -hex 10</code></pre>
53
54 <p>Now we define the TOTP configuration for our user. If you were
55 setting this up for multiple users you would make one entry per line.
56 Open <strong>/etc/users.oath</strong> and add this line.
57 <em>user</em> is the username of the account you will SSH into.
58 Replace the long string of numbers and letters with the secret key
59 you just generated.</p>
60
61 <pre><code>HOTP/T30/6 <em>user</em> - <em>00112233445566aabbcc</em></code></pre>
62
63
64 <h2>Configure PAM</h2>
65 <p>Now we need to tell PAM to use OATH to authenticate sshd. Do that
66 by opening <strong>/etc/pam.d/sshd</strong> and adding the following
67 line to the top of the file.</p>
68
69 <pre><code>auth sufficient pam_oath.so usersfile=/etc/users.oath window=30 digits=6</code></pre>
70
71 <p>This tells PAM to consider a valid 6 digit code as fully authenticated
72 and to skip any other processing that may normally occur, such as
73 requesting a password.</p>
74
75 <h2>Configure SSHD</h2>
76 <p>We need to make a few changes to the sshd configuration to allow
77 OATH to work properly. Open the sshd configuration file at
78 <strong>/etc/ssh/sshd_config</strong> and make the following changes.</p>
79
80 <pre><code>AuthenticationMethods publickey,keyboard-interactive
81PubkeyAuthentication yes
82PasswordAuthentication no
83ChallengeResponseAuthentication yes
84UsePAM yes</code></pre>
85
86 <p>The <strong>AuthenticationMethods</strong> line specifically tells
87 sshd that a user needs to both have an authorized SSH key and know
88 the proper 6 digit code to login.</p>
89
90 <p>Restart sshd to apply the changes</p>
91
92 <pre><code>systemctl restart sshd</code></pre>
93
94 <h2>Test the Changes</h2>
95 <p>From your client ssh into your server as normal. Instead of
96 connecting as you have been, you should now see a prompt for your
97 one time password. You can use <strong>oathtool</strong> to get
98 the code. Again, replace the long string of numbers and letters
99 with the secret key you generated on the server.</p>
100
101 <pre><code>oathtool --totp -d6 <em>00112233445566aabbcc</em></code></pre>
102
103 <p>Enter that 6 digit code into the prompt and you will be logged
104 into your server.</p>
105
106 <p>Now, in the unlikely event that your SSH private key is stolen,
107 an attacker still won't be able to access your server!</p>
108
109 <h2>Managing your TOTP</h2>
110 <p>You probably don't want to run the oathtool command everytime you
111 need your code, and while you could make an alias, that would require
112 storing your secret key in plaintext. Here are some better options.</p>
113
114 <ul>
115 <li><strong>pass otp</strong> is an extension to the command-line
116 password manager <strong>pass</strong> for handling TOTP.
117 Use this if you are already using pass</li>
118 <li><strong>KeePassXC</strong> is a graphical password
119 manager that can manage TOTP</li>
120 <li><strong>Gnome Authenticator</strong> is a graphical
121 TOTP manager for the GNOME desktop environment</li>
122 </ul>
123
124 <p>You may also want to generate a QR code for easy setup on another
125 device. Rerun the same oathtool command as before with the -v flag
126 to get the base32 version of your secret key.</p>
127
128 <pre><code>oathtool --totp -v -d6 <em>00112233445566aabbcc</em>
129--------------------------------
130Hex secret: 00112233445566aabbcc
131Base32 secret: <strong>AAISEM2EKVTKVO6M</strong>
132Digits: 6
133Window size: 0
134TOTP mode: SHA1
135Step size (seconds): 30
136</code></pre>
137
138 <p>Then use qrencode to generate the QR code image.</p>
139
140 <pre><code>qrencode -o <em>totp.png</em> 'otpauth://totp/<em>user</em>@<em>server</em>?secret=<em>AAISEM2EKVTKVO6M</em>'</code></pre>
141
142 </main>
143
144<p>
145<hr>
146Consider <a href=../donate.html>donating</a> if this article was useful.
147<a class=qr href=../images/bitcoin.png>[BTC]</a>
148</p>
149 </main>
150 <footer>
151 <a href=../kb.html>Knowledge Base</a>
152 <br>
153 <a href=../index.html>www.chudnick.com</a>
154 </footer>
155</body>
156</html>
157