PureOS how-to: System U2F Authentication

This is a guide for setting up system U2F authentication on PureOS. All of the files used for this configuration are stored outside of the home folder, so home folder encryption should be compatible with this approach. While I am using a YubiKey, any U2F-compatible device should do the trick.

Using this configuration, I have been prompted to authenticate with U2F in the following situations:

  • system login
  • unlocking lock screen
  • sudo commands
  • unlocking Settings panels
  • installing software from Software
  • unlocking attached LUKS drives
  • …there are probably other situations I have not run into yet.

Read this in it’s entirety before proceeding, as it is possible to lock yourself out partially or wholly.

1. Update PureOS and install dependencies:

  • sudo apt-get update && sudo apt-get full-upgrade

    • All lines formatted as above are to be entered in the terminal.
  • If updates were installed, reboot before proceeding.

  • sudo apt-get install libpam-u2f scdaemon pamu2fcfg yubikey-manager

    • While I need yubikey-manager, you may need something else if using a different make of U2F device. Refer to the documentation for your device as needed.

Do not proceed until you have these successfully installed.

2. Enable Linux udev rules for U2F devices:
udev is the Linux device manager which handles events when USB devices are added and removed. Custom rules need to be added to properly identify U2F devices and provide applications access. The rules file linked below supports multiple makes and models of U2F devices. If yours is not included in the list, see the device manufacturer about the udev rules needed for U2F.

  • sudo mkdir -p /etc/udev/rules.d/

    • You may get an error that the folder exists. You can safely ignore that error.
  • Open in new window (ctrl+click link): https://raw.githubusercontent.com/Yubico/libu2f-host/master/70-u2f.rules

  • Select all and copy content (ctrl+a, ctrl+c)

  • nano 70-u2f.rules

  • Paste and save (ctrl + shift + v, ctrl + x, y, return)

  • sudo mv 70-u2f.rules /etc/udev/rules.d/

  • sudo udevadm control --reload-rules && sudo udevadm trigger

  • lsusb

If this was successful, you will see something describing your U2F device as an attached device. If you do not, stop here and troubleshoot this issue.

3. Register your U2F device(s):
Here we will tell the system which U2F devices can be used for authentication.

Primary U2F device:

  • Connect U2F device.
  • mkdir u2f
  • pamu2fcfg --origin=pam://localhost > u2f/keys
  • Touch the device when it lights up or you are otherwise prompted.
    • Note that some U2F devices do not require a touch and do not light up.

Backup U2F device(s):
When setting up security like this, it is always a good idea to have at least one backup U2F device that you store somewhere safe – and almost always a bad idea to not have a spare. If you do not have a spare to configure now, you can do so later.

  • Connect backup U2F device.
  • pamu2fcfg -n --origin=pam://localhost >> u2f/keys
  • If needed, touch the device when it lights up or you are otherwise prompted.
  • Repeat for all backup devices.

Move registration to /etc:

  • sudo mv u2f /etc

4. Make U2F an authentication requirement:
As far as I have experienced so far, this method requires U2F for literally every situation in which you must enter your password. It is possible to require it for only certain situations, such as login, sudo, unlocking the screen, etc. See @lipu’s guide and the other sources listed at the bottom of this guide for more information on that approach.

  • sudo nano /etc/pam.d/common-auth

  • Add (or, if adding new keys after initial setup, un-comment) this to the bottom of the file:
    auth required pam_u2f.so cue no detect origin=pam://localhost authfile=/etc/u2f/keys

    • Configuration options from most secure to least:
      • Omit “cue no detect” to prevent prompting of any kind. Incorrect password and absent key failures both appear to be an incorrect password to the user.

      • Leave “cue no detect” in the above line if you want to be prompted to touch the device only when it is present. An absent key appears to be an incorrect password.

      • Omit “no detect” to always be prompted to touch the device, even when the key is not present. Arguably the least secure setup, as it reveals that a second factor exists when a key is absent.

  • Save and exit (ctrl+x, y, return).


5. CRITICAL: Test U2F Authentication:

Without closing current terminal, open a new terminal window.

  • sudo echo success

  • Enter account password, as usual for sudo.

  • If so configured, you will be prompted to touch the device, and the U2F device will then blink (if supported); touch it.

If you are not prompted to touch the device when expected (depends on configuration outlined above), or the device does not blink when expected, your password fails to be accepted, or authentication otherwise fails:

  • Close test terminal window (in which you ran echo), and return to the previous terminal window (in which you edited common-auth).

  • sudo nano /etc/pam.d/common-auth

  • Remove the line you added above:
    auth required pam_u2f.so cue no detect origin=pam://localhost authfile=/etc/u2f/keys

  • Save and exit (ctrl+x, y, return).

  • sudo rm -r /etc/u2f

  • Close terminal, and re-read this before trying again. :slight_smile:

If everything was done correctly, you will see “success”.

  • Repeat the test phase for each registered U2F device.
  • You can now safely close terminal and go about your day with the added peace of mind knowing that you have system U2F authentication!

Appendix: Adding additional U2F device(s) later:

  • sudo nano /etc/pam.d/common-auth

  • Comment out (add “#” to front of the line):
    auth required pam_u2f.so cue no detect origin=pam://localhost authfile=/etc/u2f/keys

  • Save and exit (ctrl+x, y, return).

  • sudo rm -r /etc/u2f

  • Begin again at Step 3, above.

Sources & Inspirations:


  • Added pam configuration options in section 4 based on an option I learned about.
  • Clarified section on adding additional keys later.
  • De-YubiKey’d the guide; added some notes about other device manufacturers.
  • Changed method of obtaining udev rules from curl to copy, paste, move.

Thanks for making such a good write-up for PurOS!


Glad to, I hope it helps some people :slight_smile:

1 Like

This might be a good addition to the PureOS wiki at https://tracker.pureos.net/w/pureos/tips/

What do you think?

1 Like

Good idea. We’re currently busy, but we will check out and perhaps add it.

1 Like

Personally I don’t like the call to curl to download the udev rules file. While the file itself is readable and quickly vetted, I think it is a bad practice to download files and install them with curl, it’s hard to know if they’ll always be at the URI you point to, if they have gone through proper review, or even are not malicious. I note that the file you point to is at GitHub and that it is meant to work with udev > 188. On PureOS I believe the default is to use systemd-udevd and I’ve had issues mixing different udev rules with different udev implementations.

I am happy to rework it to meet the need there. The idea with curl was to minimize clicks, etc. I’m sure I can find an acceptable solution, though.

If we were to create a wiki article for it, we could just get folks to copy and paste the needed udev rule into a new file on their computer. The file linked above does include the rules for a YubiKey, U2F Zero, Nitrokey FIDO U2F, and etc, so theoretically one only needs the rule for the key they have.

I’ll have to test this out with my Solo Key once I have a spare moment or five. Might have to make some changes compared to their udev rules and the ones from Yubico.

Perhaps better to include those rules in the distro?

Setting up U2F is needlessly complicated, which is a shame given how easy it is to use once enabled. So any convenience provided by the distro would be welcome, even if only for people comfortable doing this at the command prompt.

(Ultimately, I would like to see 2FA directly supported in Gnome Settings!)

1 Like

As for avoiding curl, it should be a simple change to downloading the file, then moving it. Or creating an empty file with the appropriate name, and pasting in what we need.

As for the source of this file, it is the one provided by Yubico directly – this is the same file linked from their own help documents.

I put this guide together after working through the process myself, using Lipu’s guide, among other resources, to get it working properly on PureOS. After putting the guide together I happened to encounter a need to reinstall my OS, which presented a wonderful opportunity to put this guide to the test. I can say that following it as written, you can get U2F set up within 5 minutes, provided you are comfortable. An inexperienced user probobly would not take all that much longer with it.

1 Like

We’re doing work packaging udev rules: https://tracker.pureos.net/T694 While we’re currently focused on the Librem Key, the udev rules should work for any key. I’m having issues with udev on local systems and don’t have the spare cycles to work on this at the moment, but hope to invest some time in it in the near future.

1 Like

This would be a great addition, as would adding something in GNOME settings, as lipu suggested, to facilitate U2F setup. If libpam-u2f, scdaemon, pamu2fcfg, yubikey-manager, and/or any other dependency could be included at install, or automatically installed when needed based on the token model (along the lines with how printers are added) when enabling U2F, it would make this kind of security extremely accessible to average bears.

Just imagine a nice little “Two-Factor Authentication” or “U2F” button there somewhere around the password field.

1 Like

I updated the guide to de-Yubi things, changed the method of obtaining the udev rules, and added some notes about other manufacturers.