How to Set Up Hardware Authentication in Omarchy: Fingerprint and FIDO2 Setup Guide

Omarchy configures hardware authentication by integrating PAM modules (pam_fprintd for fingerprints, pam_u2f for FIDO2 keys) and exposing menu-driven setup scripts that handle hardware detection, package installation, PAM stack modification, and credential enrollment automatically.

Hardware-based authentication in the Omarchy desktop environment eliminates repetitive password entry for sudo and system authorization dialogs. Whether your laptop has a built-in fingerprint sensor or you prefer a portable FIDO2 security key like a YubiKey, Omarchy provides streamlined setup paths through its unified menu system. This guide walks through the complete implementation based on the actual source code in the basecamp/omarchy repository.

---

Fingerprint Authentication Setup

Omarchy's fingerprint support targets laptops with compatible sensors and implements a smart clamshell gate that detects when your lid is closed.

How Fingerprint Authentication Works in Omarchy

The fingerprint flow uses four core components according to the Omarchy source:

1. Hardware detection – pam_fprintd identifies available fingerprint readers
2. Clamshell gate – omarchy-hw-laptop-closed skips the sensor when the lid is shut, falling back to password
3. PAM integration – pam_fprintd.so is prepended to /etc/pam.d/sudo and /etc/pam.d/polkit-1
4. Enrollment storage – fingerprints are recorded under /etc/fprintd/

The setup script bin/omarchy-setup-security-fingerprint automates this entire pipeline.

Starting Fingerprint Setup from the Omarchy Menu

Navigate through Setup → Security → Fingerprint in the Omarchy menu, or launch directly:

# Launch via floating terminal presentation mode (recommended)

omarchy-launch-floating-terminal-with-presentation omarchy-setup-security-fingerprint

# Or run directly with sudo privileges

sudo omarchy-setup-security-fingerprint

The script will:

• Verify fingerprint hardware availability
• Ensure pam_fprintd dependencies are present
• Insert the clamshell gate and pam_fprintd.so rules into PAM configuration
• Execute fprintd-enroll $USER to capture your fingerprint
• Store credentials under /etc/fprintd/

Verifying Fingerprint PAM Configuration

After setup, confirm the configuration with:

grep pam_fprintd /etc/pam.d/sudo /etc/pam.d/polkit-1

Expected output shows entries like:

/etc/pam.d/sudo:auth sufficient pam_fprintd.so
/etc/pam.d/polkit-1:auth sufficient pam_fprintd.so

Removing Fingerprint Authentication

To completely revert fingerprint setup:

omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-fingerprint

The removal script bin/omarchy-remove-security-fingerprint strips PAM entries, deletes enrolled prints, and cleans up configuration files.

---

FIDO2 Security Key Setup (YubiKey and Compatible Devices)

For hardware authentication with FIDO2 keys, Omarchy uses the libfido2 library paired with the pam-u2f PAM module.

FIDO2 Architecture in Omarchy

The FIDO2 implementation in bin/omarchy-setup-security-fido2 follows this pattern:

Component	Function
libfido2	Core FIDO2/U2F library for hardware communication
pam_u2f.so	PAM module that validates security key presence
pamu2fcfg	Utility that generates the key handle and credential files
/etc/fido2/fido2	Secure storage location for enrolled key credentials

Important limitation: Per the Omarchy source, FIDO2 authentication applies to sudo and Polkit dialogs only—the lock screen is not affected and continues requiring your password.

Starting FIDO2 Setup from the Omarchy Menu

Access via Setup → Security → Fido2 or run:

omarchy-launch-floating-terminal-with-presentation omarchy-setup-security-fido2

The script executes this sequence automatically:

1. Hardware probe – runs fido2-token -L to detect connected security keys
2. Package installation – installs libfido2 and pam-u2f via omarchy-pkg-add
3. Key enrollment – executes pamu2fcfg, prompting you to touch your device
4. Credential storage – writes the resulting key handle to /etc/fido2/fido2
5. PAM modification – inserts this rule at the top of /etc/pam.d/sudo and /etc/pam.d/polkit-1:

auth sufficient pam_u2f.so cue authfile=/etc/fido2/fido2

Manual FIDO2 Enrollment (If Needed)

Should you need to re-enroll a key without full reconfiguration:

# Ensure packages are installed

sudo omarchy-pkg-add libfido2 pam-u2f

# Generate new credential

pamu2fcfg > /etc/fido2/fido2

# Follow the prompt to touch your security key

Verifying FIDO2 PAM Configuration

Check that both files contain the pam_u2f directive:

grep pam_u2f /etc/pam.d/sudo /etc/pam.d/polkit-1

Removing FIDO2 Authentication

Complete removal is handled by:

omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-fido2

The removal script bin/omarchy-remove-security-fido2 deletes /etc/fido2/fido2, strips PAM rules, and optionally removes libfido2 and pam-u2f.

---

Menu Integration and UI Detection

Both hardware authentication methods are declared in default/omarchy/omarchy-menu.jsonc:

• Line 177 – fingerprint entry with action omarchy-setup-security-fingerprint
• Line 178 – FIDO2 entry with action omarchy-setup-security-fido2

Each action launches in a floating terminal with presentation mode, ensuring the enrollment prompts remain visible and focused.

The Polkit integration layer (shell/plugins/polkit/PolkitModel.js) detects which PAM modules are present—pam_fprintd.so or pam_u2f.so—and surfaces appropriate UI prompts during authentication dialogs.

---

What the Clamshell Gate Does for Fingerprint Users

The clamshell gate (omarchy-hw-laptop-closed) is a uniquely Omarchy feature documented in migration [migrations/1784818437.sh](https://github.com/basecamp/omarchy/blob/quattro/migrations/1784818437.sh). It solves a practical problem: when your laptop lid is closed and connected to external monitors, the fingerprint sensor is inaccessible. The gate detects this state and immediately falls through to password authentication, preventing timeout delays.

---

Summary

• Fingerprint authentication in Omarchy uses pam_fprintd, includes a smart clamshell gate for closed-lid scenarios, and stores credentials under /etc/fprintd/
• FIDO2 authentication relies on pam_u2f with credentials stored in /etc/fido2/fido2, affecting sudo and Polkit but not the lock screen
• Both methods are configured through dedicated scripts launched from Setup → Security in the Omarchy menu
• The setup scripts handle hardware detection, package installation, PAM file modification, and credential enrollment automatically
• Removal scripts completely reverse all changes when hardware authentication is no longer needed

---

Frequently Asked Questions

Does fingerprint authentication work when my laptop lid is closed?

Yes, Omarchy's clamshell gate automatically detects closed-lid states and skips the fingerprint sensor, immediately presenting the password prompt. This prevents authentication timeouts when your laptop is docked with external monitors. The gate is implemented via omarchy-hw-laptop-closed prepended to the PAM stack in [migrations/1784818437.sh](https://github.com/basecamp/omarchy/blob/quattro/migrations/1784818437.sh).

Can I use FIDO2 for unlocking the lock screen?

No. According to the Omarchy source code, FIDO2 authentication does not affect the lock screen. The pam_u2f.so rules are added only to /etc/pam.d/sudo and /etc/pam.d/polkit-1. You would need additional PAM configuration to enable security key unlocking, which Omarchy does not implement by default.

What happens if my fingerprint sensor or FIDO2 key fails?

Both PAM configurations use sufficient rather than required control flags, meaning fallback to password authentication is always available. If the hardware is unavailable, damaged, or the credential fails to validate, PAM continues to the next authentication module—the standard password prompt.

Are the setup packages installed system-wide or per-user?

Packages (libfido2, pam-u2f, fprintd dependencies) are installed system-wide via omarchy-pkg-add. However, credentials are user-specific—the fingerprint enrollment captures $USER, and FIDO2 keys are registered per physical device touch during pamu2fcfg execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}