How Omarchy Configures Security for Fingerprint and FIDO2 Hardware Authentication

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:

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:

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 file determines fingerprint availability by parsing raw PAM configuration text. The fingerprintConfiguredFromPamConfig function uses a regular expression to detect active fingerprint modules:

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:

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 addresses a critical security requirement: protecting the FIDO2 credential file from unauthorized modification. The script enforces strict ownership and permissions:

# 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 script exercises the complete registration, usage, and removal flow for FIDO2 devices. For fingerprint support, fingerprint-package-test.sh verifies proper package installation and PAM integration, while 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 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 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.

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