# How Omarchy Configures Security for Fingerprint and FIDO2 Hardware Authentication

> Learn how Omarchy configures security for fingerprint and FIDO2 hardware authentication using PAM, Polkit, and Quickshell UI. Secure your lock screens and commands today.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-10

---

**Omarchy implements hardware-backed authentication by integrating Linux PAM, Polkit, and Quickshell UI components to support fingerprint readers and FIDO2 security keys across lock screens and privileged commands.**

Omarchy provides a comprehensive **Omarchy security fingerprint FIDO2 hardware authentication** framework that bridges low-level Linux authentication modules with modern desktop interfaces. The implementation spans hardware detection scripts, PAM configuration management, and real-time UI state synchronization to deliver seamless biometric and hardware token support throughout the system.

## Fingerprint Authentication Architecture

### Hardware Detection and PAM Configuration

Fingerprint support begins with hardware detection in `bin/omarchy-hw-fingerprint`. This helper script probes for a usable fingerprint reader and reports success or failure to the UI layer. The system stores its PAM configuration in `/etc/pam.d/omarchy-lock-fingerprint`, which defines the authentication stack for the lock screen.

When the lock screen activates, the Quickshell-based interface checks the `fingerprintConfigured` flag before exposing the biometric authentication path. This prevents the UI from displaying fingerprint options on devices lacking proper hardware or configuration.

### Quickshell Lock Screen Integration

The lock screen implementation in `shell/plugins/lock/Service.qml` manages the fingerprint authentication flow through two critical properties:

```qml
property bool fingerprintAuthenticating: false
property bool fingerprintConfigured: false

```

When the screen locks and `fingerprintConfigured` returns true, the UI triggers a PAM probe via the `fingerprintPam` object. The interface switches to a square fingerprint card, hides the password field, and begins authentication:

```qml
if (root.lockRequested && root.fingerprintConfigured && !fingerprintPam.active) {
    fingerprintAuthenticating = true
    if (!fingerprintPam.start()) {
        fingerprintAuthenticating = false
    }
}

```

### Polkit Model and PAM Parsing

The [`shell/plugins/polkit/PolkitModel.js`](https://github.com/omacom/omarchy/blob/main/shell/plugins/polkit/PolkitModel.js) file determines fingerprint availability by parsing raw PAM configuration text. The `fingerprintConfiguredFromPamConfig` function uses a regular expression to detect active fingerprint modules:

```javascript
function fingerprintConfiguredFromPamConfig(raw) {
  // Look for a pam_fprintd line that isn't commented out
  return /^\s*auth\s+required\s+pam_fprintd\.so/.test(raw);
}

```

This boolean evaluation drives UI state, ensuring fingerprint options only appear when the underlying PAM stack supports biometric verification.

## FIDO2 Security Key Implementation

### Registration and Directory Structure

The `bin/omarchy-setup-security-fido2` script establishes the FIDO2 infrastructure by creating a dedicated state directory at `$XDG_STATE_HOME/omarchy/fido2`. Within this directory, the script generates an `authfile` that stores the credential registration. The setup process uses `pamu2fcfg` to register the hardware key, then prompts the user to touch the device to complete enrollment.

The script writes a specific PAM configuration to `/etc/pam.d/omarchy-sudo-fido2` and corresponding Polkit rules that point to the registration directory. After configuration, the script validates the setup by executing a privileged test:

```bash
echo "Configuring sudo for FIDO2 authentication..."

# …create /etc/pam.d/omarchy-sudo-fido2 pointing at $authfile…

echo -e "\nTesting FIDO2 authentication with sudo..."
echo -e "Touch your FIDO2 key when prompted.\n"
if sudo echo "FIDO2 authentication test successful"; then
    echo -e "\e[32m\nPerfect! FIDO2 authentication is now configured.\e[0m"
fi

```

### System Integration and Removal

FIDO2 authentication applies to both sudo commands and Polkit authorization dialogs. The `bin/omarchy-remove-security-fido2` script completely reverses the configuration by deleting the `$XDG_STATE_HOME/omarchy/fido2` directory, revoking PAM and Polkit entries, and removing associated packages. This ensures clean removal without orphaned configuration files.

## Security Hardening and Migration

### Authfile Ownership Protection

The migration script [`migrations/1787494718.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1787494718.sh) addresses a critical security requirement: protecting the FIDO2 credential file from unauthorized modification. The script enforces strict ownership and permissions:

```bash

# Take ownership of the FIDO2 authfile so it cannot be rewritten without root

chmod 600 "$authfile"
chown root:root "$authfile"
omarchy-notification-send -u critical -g "" "FIDO2 authfile needs attention" "$1 $2" || true

```

By setting the file owner to `root:root` and permissions to `600`, the system guarantees that attackers without root privileges cannot overwrite or tamper with hardware key credentials. This privilege-aware design ensures the authentication chain remains intact even if the user session is compromised.

## Testing and Validation

### Automated Test Coverage

Omarchy validates its hardware authentication stack through comprehensive shell tests in the `test/shell.d/` directory. The [`security-fido2-test.sh`](https://github.com/omacom/omarchy/blob/main/security-fido2-test.sh) script exercises the complete registration, usage, and removal flow for FIDO2 devices. For fingerprint support, [`fingerprint-package-test.sh`](https://github.com/omacom/omarchy/blob/main/fingerprint-package-test.sh) verifies proper package installation and PAM integration, while [`lock-fingerprint-indicator-test.sh`](https://github.com/omacom/omarchy/blob/main/lock-fingerprint-indicator-test.sh) confirms UI visibility states and symlink handling.

These tests verify edge cases including missing devices, malformed PAM configurations, and proper cleanup procedures, ensuring reliable operation across diverse hardware environments.

## Summary

- **Omarchy** integrates fingerprint authentication through `bin/omarchy-hw-fingerprint` detection, PAM configurations in `/etc/pam.d/omarchy-lock-fingerprint`, and Quickshell UI components that parse Polkit models.
- **FIDO2 hardware keys** are configured via `bin/omarchy-setup-security-fido2`, which creates protected registration files in `$XDG_STATE_HOME/omarchy/fido2` and updates system authentication stacks.
- **Security hardening** occurs through migration scripts that enforce root ownership of credential files, preventing unauthorized modification of hardware authentication data.
- **Comprehensive testing** in `test/shell.d/` validates both fingerprint and FIDO2 workflows, ensuring end-to-end reliability for physical authentication methods.

## Frequently Asked Questions

### How does Omarchy detect if a fingerprint reader is available?

Omarchy uses the `bin/omarchy-hw-fingerprint` script to probe for usable fingerprint hardware. The [`shell/plugins/polkit/PolkitModel.js`](https://github.com/omacom/omarchy/blob/main/shell/plugins/polkit/PolkitModel.js) file then parses `/etc/pam.d/omarchy-lock-fingerprint` using the `fingerprintConfiguredFromPamConfig` function, which scans for uncommented `pam_fprintd.so` entries. This boolean result propagates to the Quickshell UI, which only displays fingerprint options when the hardware and PAM configuration are both present.

### What files does the FIDO2 setup script modify?

The `bin/omarchy-setup-security-fido2` script creates the directory `$XDG_STATE_HOME/omarchy/fido2` to store the `authfile` credential register. It writes PAM configuration to `/etc/pam.d/omarchy-sudo-fido2` and establishes Polkit rules pointing to this directory. The script also invokes `pamu2fcfg` to generate the hardware key mapping, then tests the configuration using a privileged sudo command.

### How does Omarchy prevent unauthorized modification of FIDO2 credentials?

The migration script [`migrations/1787494718.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1787494718.sh) secures the FIDO2 `authfile` by setting ownership to `root:root` and permissions to `600`. This ensures only the root user can read or modify the credential data. An attacker compromising the user session cannot rewrite the authentication file to bypass hardware key requirements, maintaining the integrity of the privilege escalation chain.

### Can fingerprint and FIDO2 authentication be used simultaneously?

Yes. Omarchy treats these as separate authentication paths within the PAM and Polkit stacks. The fingerprint integration targets the lock screen via `/etc/pam.d/omarchy-lock-fingerprint`, while FIDO2 configuration in `/etc/pam.d/omarchy-sudo-fido2` handles privileged command execution. Both methods can be configured simultaneously, allowing users to unlock the screen with biometrics while reserving hardware key authentication for administrative tasks.