Windows Hello on Ubuntu setup guide

Windows-Hello-on-Ubuntu.md

Windows Hello-Style Authentication on Ubuntu 24.04

This guide sets up facial recognition (using IR camera) and fingerprint authentication on Ubuntu, similar to Windows Hello.

Prerequisites

• Ubuntu 24.04 with GNOME
• Windows Hello compatible IR camera
• Fingerprint sensor (optional)

Step 1: Install Howdy (Facial Recognition)

Add the Howdy PPA and install

sudo add-apt-repository -y ppa:boltgolt/howdy
sudo apt update
printf 'y\nb\n' | sudo apt install -y howdy

Install Python dependencies

sudo apt install -y python3-numpy python3-opencv
sudo pip3 install dlib --break-system-packages

Create howdy command wrapper

echo '#!/bin/bash
exec python3 /lib/security/howdy/cli.py "$@"' | sudo tee /usr/local/bin/howdy > /dev/null
sudo chmod +x /usr/local/bin/howdy

Fix Python 3 compatibility in PAM module

sudo sed -i 's/import ConfigParser/import configparser as ConfigParser/' /lib/security/howdy/pam.py

Step 2: Identify Your IR Camera

List your video devices:

v4l2-ctl --list-devices

Check which device is the IR camera (usually labeled "Integrated I" vs "Integrated C" for color):

v4l2-ctl -d /dev/video0 --info
v4l2-ctl -d /dev/video2 --info

The IR camera typically outputs grayscale (GREY format).

Step 3: Configure Howdy

Set the IR camera device

sudo sed -i 's|^device_path = .*|device_path = /dev/video2|' /lib/security/howdy/config.ini

Replace /dev/video2 with your actual IR camera device.

Adjust dark threshold for IR camera

sudo sed -i 's|^dark_threshold = .*|dark_threshold = 100|' /lib/security/howdy/config.ini

Disable snapshots (avoids permission issues)

sudo sed -i 's/^capture_failed = true/capture_failed = false/' /lib/security/howdy/config.ini
sudo sed -i 's/^capture_successful = true/capture_successful = false/' /lib/security/howdy/config.ini

Step 4: Install and Configure IR Emitter Tool

The IR emitters need to be enabled for the camera to see your face.

Download and install linux-enable-ir-emitter

cd /tmp
curl -sL "https://github.com/EmixamPP/linux-enable-ir-emitter/releases/download/6.1.2/linux-enable-ir-emitter-6.1.2-release.systemd.x86-64.tar.gz" -o ir-emitter.tar.gz
sudo tar -C / --no-same-owner -m -xzf ir-emitter.tar.gz

Configure the IR emitter

Run the interactive configuration tool:

linux-enable-ir-emitter configure

Follow the prompts to detect which camera control enables the IR emitters.

Enable the systemd service

sudo systemctl enable linux-enable-ir-emitter.service
sudo systemctl start linux-enable-ir-emitter.service

Step 5: Enroll Your Face

sudo howdy add

Look straight at the camera when the IR light turns on. Enter a label when prompted (e.g., "main").

Test face recognition

sudo howdy test

Step 6: Set Up Fingerprint Authentication

Enroll your fingerprint

fprintd-enroll

Swipe your finger multiple times when prompted.

Verify enrollment

fprintd-list $USER

Step 7: Configure PAM for Biometric Login

Backup the original PAM config

sudo cp /etc/pam.d/common-auth /etc/pam.d/common-auth.backup

Add Howdy to PAM

sudo sed -i '/# here are the per-package modules/a # Biometric auth (face recognition with password fallback)\nauth\tsufficient\t\t\tpam_python.so /lib/security/howdy/pam.py' /etc/pam.d/common-auth

Suppress OpenCV warnings (optional)

echo 'OPENCV_LOG_LEVEL=ERROR' | sudo tee -a /etc/environment > /dev/null

What Works Where

Method	Terminal/sudo	Lock Screen	GDM Login
Face Recognition	Yes	Yes	Yes
Fingerprint	No*	Yes	Yes
Password	Yes (fallback)	Yes (fallback)	Yes (fallback)

*Fingerprint in terminal requires additional setup and doesn't work reliably.

Useful Commands

# Face recognition
howdy list              # List enrolled face models
howdy add               # Add another face model
howdy remove <id>       # Remove a face model
howdy test              # Test face recognition
howdy disable 1         # Temporarily disable howdy
howdy disable 0         # Re-enable howdy

# Fingerprint
fprintd-list $USER      # List enrolled fingerprints
fprintd-enroll          # Enroll another finger
fprintd-delete $USER    # Delete all fingerprints

# IR Emitter
linux-enable-ir-emitter run      # Manually enable IR
linux-enable-ir-emitter configure # Reconfigure

Troubleshooting

Face detection fails with "too dark"

Increase the dark_threshold in /lib/security/howdy/config.ini

IR emitters not turning on

Reconfigure with linux-enable-ir-emitter configure

Camera in use error

Kill processes using the camera: sudo fuser -k /dev/video2

Locked out after PAM changes

Boot into recovery mode and restore the backup:

cp /etc/pam.d/common-auth.backup /etc/pam.d/common-auth

Recovery

Always keep a backup of your PAM config. If you get locked out:

1. Boot into recovery mode (hold Shift during boot)
2. Select "root shell"
3. Remount filesystem: mount -o remount,rw /
4. Restore backup: cp /etc/pam.d/common-auth.backup /etc/pam.d/common-auth
5. Reboot: reboot