Desktop Login And Linux User Authentication¶

Compatible Nitrokeys
✓ active	✓ active	⨯ inactive	⨯ inactive	✓ active	⨯ inactive	⨯ inactive	✓ active

Compatible Nitrokeys

Warning

The following guide can potentially lock you out of your computer. You should be aware of these risks, as it is recommended to first use the instructions below on a secondary computer, or after a full backup.

You might lose access to your data after configuring PAM modules.

Introduction ¶

This guide will walk you through the configuration of Linux to use FIDO Universal 2nd Factor, i.e. FIDO U2F with libpam-u2f and compatible Nitrokeys.

If you want to login to you computer using Nitrokey Pro 2, Nitrokey Storage 2 and Nitrokey Start you can visit the instructions available here.

Requirements ¶

Ubuntu 24.04 with Gnome Display Manager (GDM).

Instructions ¶

Create a backup user and give it root privileges
```
$ sudo adduser <backup_user>
$ sudo usermod -aG sudo <backup_user>
```
In case you prefer to setup U2F for a single user, and are locked out of your user session, you would still be able to login with the <backup_user>, and proceed with the maintenance.

Install libpam-u2f

On Ubuntu 24.04 it is possible to download directly libpam-u2f from the official repos

$ sudo apt install libpam-u2f

Note

Alternatively you can build libpam-u2f from Git.
To verify that the library is properly installed enter the following command:

$ file /lib/x86_64-linux-gnu/security/pam_u2f.so

The Output should be something like the following:

/lib/x86_64-linux-gnu/security/pam_u2f.so: \ ELF 64-bit LSB shared object, x86-64, version 1 (SYSV),\ dynamically linked, BuildID[sha1]=1d55e1b11a97be2038c6a139579f6c0d91caedb1, stripped

Generate the U2F config file

To generate the configuration file we will use the pamu2fcfg utility. First plug your Nitrokey (if you did not already), and enter the following command:
```
$ pamu2fcfg > ~/u2f_keys
```
Once you run the command above, you will need to touch the device while it flashes. Once done, pamu2fcfg will append its output the u2f_keys file in the format:
```
<username>:KeyHandle,PublicKey,flags
```
This will look something like the following:
```
nitrouser:fS6vQ9uWa0VizcczyZ/bvk5kcQJkIJOC/21/e7dXFe/fnONSL705EkeiUpZpL/3seAWL/qW4/mqb0/WtiZoP/NOLTRM4EEAg1ANLsfYgSzRd/AjsW3z8kJwgckbvwDUyB90ByR09XtBhuE41vMsEk6J+9CS0+ZuPSB0KXRG7z2yZpQLldjE/ijsdIdd8Ct2oXSiZ/zTb/t5kRafNJVkp=,Oo4U9XvIhI9r0WNnvoMwG5/pbgwYd4GMCYEinhWcsI2hKUebYj92JOxDsSa3zd2A9OB0ofXgB16FD2naev3YmLch==,es256,+presence
```
Note, this output was not generated directly by pamu2fcfg and contains no sensitive information. It is purely meant to show the expected format and length of the output.
Tip
- The file must be named u2f_keys
- It is recommended to first test the instructions with a single user. To configure multiple users, look under Configuring more users.
Backup

This step is optional, however it is advised to have a backup Nitrokey in the case of loss, theft or destruction of your primary Nitrokey.

To set up a backup key, repeat the procedure above, and use pamu2fcfg -n like this:
```
$ pamu2fcfg -n >> ~/u2f_keys
```
This will omit the <username> field, and the output is appended to the line with your <username>, this will look something like this:
```
<username>:Zx...mw,04...0a:xB...fw,es256,+presence:04...3f,es256,+presence
```
Securing the config file

For better security, after the config file was generated, we will move the generated file ~/u2f_keys to /etc/Nitrokey/ and change the access permissions using these commands:
```
$ sudo mkdir /etc/Nitrokey
$ sudo mv ~/u2f_keys /etc/Nitrokey/
$ sudo chmod 644 /etc/Nitrokey/u2f_keys
```
Modify the Pluggable Authentication Module PAM

The final step is to configure the PAM module files under /etc/pam.d/. In this guide we will modify the common-auth file as it handles the authentication settings which are common to all services, but other options are possible. You can modify the file with the following command:
```
$ sudo $EDITOR /etc/pam.d/common-auth
```
And add the following lines at the top of the file:
```
#Nitrokey config
auth    sufficient pam_u2f.so authfile=/etc/Nitrokey/u2f_keys cue [cue_prompt=Please touch the device.] prompt
```
Tip
- Since we are using Central Authentication Mapping, we need to tell pam_u2f the location of the file to use with the authfile option.
- If you often forget to insert the key, prompt option make pam_u2f print Insert your U2F device, then press ENTER. and give you a chance to insert the Nitrokey.
- If you would like to be prompted to touch the Nitrokey, cue option will make pam_u2f print Please touch the device. message. You can change the message in [cue_prompt=Please touch the device.].
Once we modified the common-auth, we can save and exit the file.

You can test the configuration by typing sudo ls in the terminal. You should be prompted the message Please touch the device. and have a similar output on the terminal:
```
nitrouser@nitrouser:~$ sudo ls
[sudo] password for nitrouser:  Please touch the device.
```
You can also test your configuration by logging out of the user session and logging back. A similar screen should be displayed once you you unplug/replug yout Nitrokey and type your password:

Usage ¶

After the PAM module modification, you will be able to test your configuration right away, but it is recommended to reboot your computer, and unplug/replug the Nitrokey.

Once you have properly tested the instructions in this guide (and set up a backup), it is recommended to use either the required or the requisite control flag instead of sufficient.

The flags required and requisite provide a tighter access control, and will make the Nitrokey necessary to login, and/or use the configured service.

If you need more information about Control Flags in the PAM configuration line, you may see the last section of this guide to understand the difference, and the implications of using each of them.

PAM Modules ¶

There are several PAM modules files that can be modified according to your needs:

By modifying /etc/pam.d/common-auth file, you will be able to use you Nitrokey for 2nd factor authentication for graphic login and sudo. Note: common-auth should be modified by adding the additional configuration line at the end of the file.
If you wish to use FIDO U2F authentication solely for Gnome’s graphic login, you might prefer to modify the/etc/pam.d/gdm-password
Alternatively you can just modify the /etc/pam.d/sudo file if you wish to use FIDO U2F when using the sudo command.

Control Flags ¶

In step 6 we have used the sufficient control flag to determine the behavior of the PAM module when the Nitrokey is plugged or not. However it is possible to change this behavior by using the following control flags:

required: This is the most critical flag. The module result must be successful for authentication to continue. This flag can lock you out of your computer if you do not have access to the Nitrokey.
requisite: Similar to required however, in the case where a specific module returns a failure, control is directly returned to the application, or to the superior PAM stack. This flag can also lock you out of your computer if you do not have access to the Nitrokey.
sufficient: The module result is ignored if it fails. The sufficient flag considered to be safe for testing purposes.
optional: The success or failure of this module is only important if it is the only module in the stack associated with this service+type. The optional flag is considered to be safe to use for testing purposes.

Warning

If required or requisite is set, the failure of U2F authentication will cause a failure of the overall authentication. Failure will occur when the configured Nitrokey is not plugged, lost or destroyed.
You will lose access to your computer if you mis-configured the PAM module and used the required or requisite flags.
You will also lose the ability to use sudo if you set up Central Authentication Mapping and used the required or requisite flags.
You might also lose the ability to log in using Gnome Display manager if smart card login is enforced and you used the required or. requisite flags. See Troubleshooting for further info.

Configuring more users ¶

After you tested the login with the original user and everything worked as expected, you can, if you wish to, configure u2f login for other users. To do so, pamu2fcfg takes the -u <username> option, the output can be appended to the u2f_keys file like this:

$ sudo pamu2fcfg -u <username >> /etc/Nitrokey/u2f_keys

To add a backup Nitrokey to this user, plug in your backup Nitrokey and do the same you did for the primary user:

$ sudo pamu2fcfg -n >> /etc/Nitrokey/u2f_keys

After that repeat this process for all the users you want to.

Troubleshooting ¶

Issues logging into user account using GDM ¶

In some cases, for example if you have opencs-pkcs11 installed, Gnome Display Manager (GDM) can default to enforcing smart card login as soon as any smart card (like your Nitrokey) is plugged in, even if no smart card has ever been configured. This can prevent you from logging in to your user account using u2f. If you have set the sufficient control flag, unplug all smart cards and log in using your password. To turn off smart card enforcing run the following command:

$ sudo -u gdm env -u XDG_RUNTIME_DIR -u DISPLAY DCONF_PROFILE=gdm dbus-run-session gsettings set org.gnome.login-screen enable-smartcard-authentication false