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

> Effortlessly set up hardware authentication in Omarchy with our guide. Learn to configure fingerprint and FIDO2 keys easily. Secure your system now.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-setup-security-fingerprint#L10-L36) automates this entire pipeline.

### Starting Fingerprint Setup from the Omarchy Menu

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

```bash

# 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:

```bash
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:

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

```

The removal script [`bin/omarchy-remove-security-fingerprint`](https://github.com/basecamp/omarchy/blob/quattro/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`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-setup-security-fido2#L9-L58) 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:

```bash
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:

```bash

# 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:

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

```

### Removing FIDO2 Authentication

Complete removal is handled by:

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

```

The removal script [`bin/omarchy-remove-security-fido2`](https://github.com/basecamp/omarchy/blob/quattro/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`](https://github.com/basecamp/omarchy/blob/quattro/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`](https://github.com/basecamp/omarchy/blob/main/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/main/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/main/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.