How to add a U2F key to Kubuntu 18.04
In this guide I will be showing you how to enable U2F key login on Kubuntu 18.04. I am using a key from Yubico. I have referenced my sources from the following websites:
Before you begin you should make sure to have two separate physical hardware U2F keys. I almost lost one of mine last week, and you wouldn't want to be locked out of anything should you lose yours. In this guide I will be showing you only how to enable the login in concert with password, as I haven't fully decided on if I want to enable two-factor U2F key login (password and key required for login) yet.
Also, important to note, you do not want to put configuration files on an encrypted home directory as those files will be encrypted only after you login - i.e. a great way to permanently lose your files.
STEPS
1. First thing is to install some repositories and packages:
sudo apt-get install libpam-u2f
sudo add-apt-repository ppa:yubico/stable
sudo apt-get update
sudo apt-get install libpam-yubico
2. This step is not necessary, but if you want to in future use the Yubico PAM module and use their online key verification system you can follow this step to get these packages and dependencies installed on Ubuntu.
sudo apt-get install yubikey-manager-qt
sudo apt-get install yubioath-desktop
sudo apt-get install yubikey-personalization-gui
sudo apt-get install yubikey-piv-manager
3. Generate /etc/u2f_mappings file, and set the correct permissions
a. First you will need to get the U2F key's information so insert your U2F USB key and enter the following command replacing [username] with your User Name
pamu2fcfg -u[username]
b. Copy the output into the clipboard by highlighting it and pressing SHIFT-CTRL-C, (if it ends in a % sign do not highlight or copy the % sign) it should look something like this:
username:randomcharactersfromu2fkey
c. Now you will create the /etc/u2f_mappings file
sudo nano /etc/u2f_mappings
d. Paste into this file the output from the clipboard by pressing SHIFT-CTRL-V
e. Close the file by pressing CTRL-X and selecting Y to save changes
f. You will need to now remove your first U2F key from the USB port and insert the backup USB key (only one USB key in the system at a time) and run the command again replacing [username] with your User Name
pamu2fcfg -u[username]
g. Again you will need to Copy something, but this time omit your username so from the output below:
username:randomcharactersfromu2fbackupkey
h. Only copy everything to the right of your User Name starting with the colon : key (and omitting any % sign at the end if it is there) by pressing SHIFT-CTRL-C once the desired region is highlighted
i. Again open the u2f_mappings file for editing:
sudo nano /etc/u2f_mappings
j. Paste at the end of the line you created by pressing SHIFT-CTRL-V without extra spaces so you should now have a line that looks like this:
username:randomcharactersfromu2fkey:randomcharactersfromu2fbackupkey
k. Each set of random characters should have a colon to delineate it from the username and other keys as shown above
l. Close the file again by pressing CTRL-X and selecting Y to save changes
m. Now we need to set correct permissions on the file by running:
sudo chmod 644 /etc/u2f_mappings
4. Time to test your configuration
a. In order to test you need to first understand the PAM configuration structure. In Linux distributions the Pluggable Authentication Module has a few basic ways to configure it. You can either have everything in one file /etc/pam.conf or do it the way Ubuntu does it, by having different services like sudo samba or su have individual configuration files in /etc/pam.d. This way you can have some services configured to authenticate a different way than other services. If everything is in the /etc/pam.d there is a file called /etc/pam.d/common-auth and it houses a common authentication method again for standardizing authentication across services, but enabling you to change that method by putting other authentication modules after the @include common-auth line in each different service file. This means that the authenticator will run the service specific lines after it runs through the common-auth procedure.
b. We will test with sudo to make sure your configuration is working, first go to the directory
cd /etc/pam.d
c. Look at the service files available in there
ls
d. Next edit the service specific file for sudo only
sudo nano sudo
e. After the line @include common-auth line insert the text below. Auth - this is for authentication, Sufficient: If a sufficient authentication module returns OK (yours below), the processing of modules will be stopped, pam_u2f.so is the module for the U2F standard, debug will show you debug output, authfile is the file we created earlier above, and cue tells the system to give you a message when it is necessary to tap the device (doesn't always work per method).
auth sufficient pam_u2f.so debug authfile=/etc/u2f_mappings cue
f. Save the file by pressing CTRL-X and selecting Y to save changes
g. Now open a new tab or new window on your console to instantiate a new session, and run something like the below, first inserting your U2F key into an available USB slot. When you get the prompt to enter your password, hit enter and you should see the debugging lines scroll by and your device should flash and then press the device.
sudo echo test
h. You should get the word 'test' in your console window echoed back to you, on a successful test do the above step again instead with your backup key into a free USB slot (only one U2F key inserted into a computer at a time).
i. Upon a successful test undo the lines from the sudo service first:
sudo nano sudo
j. Put a Hash sign # before the line that you had added to disable the test code to the sudo file and press CTRL-X and Y to save.
5. Make the configuration permanent
a. Now that we know you have setup the device correctly we can now start editing to make the sign in permanent
sudo nano common-auth
b. In the common-auth file we will be adding a slightly different module auth line than before. In the common-auth file you may likely find the lines below. You should notice that in the second column instead of sufficient, you have these success and default statements. What is happening here is that in the pam linux module system, lines (modules) are first tried one by one, so order matters. Normally you would have lines go one after the other. The pam_unix.so is the primary password authentication module that validates users with the encrypted /etc/shaddow file as a backend. So in this configuration the pam_unix.so is tried first, and if it successfully authenticates the user, it skips two lines (success=2), skipping the pam_deny.so line and pam_winbind.so line and going directly to the pam_permit.so line.
# here are the per-package modules (the "Primary" block)
auth [success=2 default=ignore] pam_unix.so nullok_secure try_first_pass
auth [success=1 default=ignore] pam_winbind.so krb5_auth krb5_ccache_type=FILE cached_login try_first_pass
c. We will modify this block of code so that we are now adding our U2F authentication method like we did above with the test sudo service. Modify the file such that the lines look like they do below, note that the order of success is now changed. Now our pam_u2f.so line is at the bottom and is set to skip one line, with each other line set to skip one additional line. Also missing is the debug handle from the code, and the sufficient method.
# here are the per-package modules (the "Primary" block)
auth [success=3 default=ignore] pam_unix.so nullok_secure try_first_pass
auth [success=2 default=ignore] pam_winbind.so krb5_auth krb5_ccache_type=FILE cached_login try_first_pass
auth [success=1 default=ignore] pam_u2f.so authfile=/etc/u2f_mappings cue
d. Save the file by hitting CTRL-X and Y to save changes.
e. Reboot your computer, and when presented with the login screen, insert your U2F key into a free USB port, and hit enter, then tap the device and you should be logged into your computer!
****
NOTE: If it doesn't work, you will have to use recovery options for Ubuntu in the grub menu, first doing a fsck of your drives, then using the root command line to fix issues.
****
Also, occasionally you might be notified through an update to the system that your common-auth line has custom code in it. If you allow the system to over write the changes you will have to redo the edits to the common-auth file. The system might save a common-auth-backup file that you can reference.
Comments
Post a Comment