YubiKey U2F on Ubuntu

Basic walk through of setting up U2F with YubiKey on Ubuntu 23.04 (should work on recent versions, as well). This follows the official documentation closely, removing anything not necessary for my particular setup.

N.B. this is different from challenge response, a different multifactor method. YubiKeys support multiple protocols, U2F and challenge response being two of them.


  • Ubuntu 23.04
  • YubiKey
    • I used the YubiKey 5 series: 5 NFC, 5 C, and 5 Ci. Where necessary, I used an adapter to plug in the USB-C key into an standard USB-A port.
  • Associate YubiKey U2F with your account
    • Creates a line of text in a file containing your username and the 2nd factor string
    • Move the U2F file to a secure location readable only by root
  • Create PAM configs to require U2F for certain authentication operations, e.g. login, sudo

Create two PAM configs. Creating these configs will allow us to include them rather than copying and pasting the same config lines in multiple other PAM configs in /etc/pam.d.

In these configs, we add the “cue” and “interactive” options which will prompt the user to insert the YubiKey and to touch it.

/etc/pam.d/u2f-required will be the configuration to require the YubiKey:

auth required pam_u2f.so authfile=/etc/yubico/u2f_keys cue interactive

/etc/pam.d/u2f-sufficient will be the configuration which allows using only the YubiKey without a password:

auth sufficient pam_u2f.so authfile=/etc/yubico/u2f_keys cue interactive

For the initial setup, also add the following to the "auth" lines in the above config files:

debug debug_file=/var/log/pam_u2f.log

Then, create an empty debug log file to start: 

sudo touch /var/log/pam_u2f.log

CAUTION Best to have a root shell active, in case something goes awry, and you cannot sudo anymore:

normaluser$ sudo bash

DO NOT exit this terminal until you are sure at least sudo works. 

Basic idea: in each authentication scenario (i.e. PAM config file) where you want U2F, add the line

@include u2f-required

after the line 

@include common-auth

E.g. require U2F for sudo, modify the files
  • /etc/pam.d/sudo
  • /etc/pam.d/sudo-i
These are the PAM configs I updated in /etc/pam.d:
  • gdm-password -- prompts for YubiKey at GUI login screen
  • login -- prompts for YubiKey at console login
  • polkit-1 -- prompts for YubiKey when running GUI apps requiring sudo, e.g. synaptic
  • su -- prompts for YubiKey for su
  • sudo -- prompts for YubiKey for sudo
  • sudo-i -- prompts for YubiKey for sudo -i
The first one to try should be sudo since it is easy to test. Make the modification, then open a new terminal tab/window, and run a simple sudo command, e.g. "sudo ls -l /tmp". It should prompt you to insert the device, and then to touch it:

normaluser$ sudo ls -l /tmp
[sudo] password for normaluser: 
Insert your U2F device, then press ENTER.
Please touch the device. (The YubiKey should start flashing.)
total xx
[listing of files here]

If that did not work, examine the debug log /var/log/pam_u2f.log Make any adjustments, close out that sudo terminal tab/window, and launch a new one.

Once you are satisfied that everything works, you can remove the “debug debug_file=/var/log/pam_u2f.log” from /etc/pam.d/u2f_required and /etc/pam.d/u2f_sufficient

Minor annoyance: the GUI popup dialog for sudo authentication won’t accept just ENTER when it says “Insert your U2F device, then press ENTER”: you have to type in at least a SPACE for it to register that you have acknowledged the prompt, and are ready to touch the YubiKey.

No comments:

Post a Comment

Note: Only a member of this blog may post a comment.