How Omarchy Handles User Authentication: PAM, Polkit, and Hardware Security

Omarchy delegates user authentication to Linux PAM (Pluggable Authentication Modules) and Polkit, providing a unified interface that supports password, fingerprint, and FIDO2 hardware keys for the lock screen, sudo, and privileged actions.

The basecamp/omarchy repository implements a sophisticated authentication layer that sits atop standard Linux security infrastructure rather than replacing it. By combining PAM service configuration with custom QML UI components, Omarchy user authentication delivers adaptive dialogs that automatically select the appropriate method based on available hardware and system state.

PAM-Based Authentication Architecture

Omarchy relies entirely on the Pluggable Authentication Modules (PAM) framework to verify credentials. Rather than handling passwords directly, the system configures PAM service files and acts as a Polkit agent to mediate privilege escalation requests.

The architecture distinguishes between three authentication contexts:

• Lock screen access – Managed by dedicated PAM service files generated at runtime
• Sudo commands – Standard PAM stack with optional hardware modules injected via setup scripts
• Polkit privileged actions – GUI dialogs that appear for package management and system configuration changes

All authentication methods ultimately validate through PAM, ensuring compatibility with existing Linux security policies and maintaining system audit trails.

Lock Screen Configuration

For lock screen authentication, the omarchy-apply-lock script generates PAM service definitions dynamically. Located at bin/omarchy-apply-lock, this utility writes /etc/pam.d/omarchy-lock-password unconditionally and conditionally creates /etc/pam.d/omarchy-lock-fingerprint only when the system detects a fingerprint sensor.

# Generate lock screen PAM configuration

sudo omarchy-apply-lock

The script inspects hardware capabilities before enabling biometric unlock, ensuring the lock screen only offers fingerprint authentication when the underlying hardware actually exists on the device.

Real-Time Polkit Authentication

For privileged operations like package installation, Omarchy registers a custom Polkit agent via shell/plugins/polkit/PolkitAgent.qml. This QML component registers the service /org/omarchy/PolkitAgent with the system bus to intercept authentication requests.

When Polkit requests credentials, the agent displays a modal dialog that adapts its input method based on the underlying PAM stack configuration. The companion PolkitModel.js file handles PAM parsing logic, including the fingerprintConfiguredFromPamConfig function that scans /etc/pam.d/polkit-1 to determine available authentication methods.

To trigger the authentication dialog manually:

# Attempt a privileged action (e.g., installing a package)

omarchy-pkg-add some-package

If the user lacks active privileges, the Polkit dialog appears automatically, offering fingerprint authentication when the PAM stack supports it.

Fingerprint Authentication Support

Enabling fingerprint authentication requires running omarchy-setup-security-fingerprint from the bin/ directory. This script modifies three critical PAM service files to insert pam_fprintd.so entries:

1. /etc/pam.d/sudo – Enables biometric verification for command-line elevation
2. /etc/pam.d/polkit-1 – Activates fingerprint prompts in the GUI dialog
3. Lock screen services – Configures the optional fingerprint unlock path

# Enable fingerprint for sudo, polkit, and lock screen

omarchy-setup-security-fingerprint

The script reloads authentication agents immediately after modification. Removal is handled by omarchy-remove-security-fingerprint, which strips PAM entries without disrupting standard password authentication.

FIDO2 Hardware Key Integration

For hardware-backed two-factor authentication, Omarchy supports FIDO2/U2F security keys through the pam_u2f.so module. The omarchy-setup-security-fido2 script creates PAM rules for both sudo and polkit-1 services.

# Configure FIDO2 key for privileged operations

omarchy-setup-security-fido2

After modifying the PAM stack, the script performs a test sudo command to verify key registration. The counterpart script omarchy-remove-security-fido2 reverses these changes when hardware needs replacement or removal.

Smart UI Switching and Lid Detection

The authentication interface dynamically switches between password and fingerprint modes based on runtime hardware state. In PolkitAgent.qml, the fingerprintMode property evaluates to true only when three specific conditions align:

• fingerprintConfigured returns true from PolkitModel.fingerprintConfiguredFromPamConfig, which verifies pam_fprintd.so exists in /etc/pam.d/polkit-1
• The laptop lid is open (monitored via omarchy-hw-laptop-closed)
• The dialog is active without a pending password response already in progress

A background process (laptopClosedProc) continuously monitors lid state. When the laptop closes, the UI immediately falls back to password entry even if a fingerprint sensor is present, preventing accidental lockouts when the device is docked or the sensor inaccessible.

Summary

• Core Infrastructure: Omarchy user authentication relies on Linux PAM and Polkit, maintaining compatibility with standard security auditing and centralized policy management.
• Lock Screen: The omarchy-apply-lock script dynamically generates PAM service files for password and conditional fingerprint authentication.
• Hardware Support: Dedicated scripts (omarchy-setup-security-fingerprint and omarchy-setup-security-fido2) inject pam_fprintd.so or pam_u2f.so into the sudo and polkit PAM stacks.
• UI Adaptation: PolkitAgent.qml and PolkitModel.js provide real-time PAM parsing and lid-state detection to switch between biometric and password prompts automatically.
• Security Model: All credential verification occurs through kernel-mediated PAM modules, ensuring Omarchy never handles raw passwords directly in application code.

Frequently Asked Questions

How does Omarchy detect whether fingerprint authentication is available?

Omarchy scans the PAM configuration at runtime. The fingerprintConfiguredFromPamConfig function in shell/plugins/polkit/PolkitModel.js reads /etc/pam.d/polkit-1 line-by-line and returns true if any auth directive includes pam_fprintd.so. This allows the UI to offer fingerprint prompts only when the underlying PAM stack actually supports biometric verification.

Can I use both fingerprint and FIDO2 security keys simultaneously?

Yes, though they serve different workflow purposes. The omarchy-setup-security-fingerprint script configures pam_fprintd.so for biometric convenience, while omarchy-setup-security-fido2 adds pam_u2f.so for hardware-backed two-factor authentication. Both modules can coexist in the PAM stack, though the exact authentication flow depends on your PAM configuration's sufficient and required directive ordering.

Why does the fingerprint option disappear when I close my laptop lid?

Omarchy intentionally disables fingerprint prompts when the laptop is closed to prevent authentication failures. A background process monitors omarchy-hw-laptop-closed and updates the laptopClosed flag in the Polkit model. The fingerprintMode property in PolkitAgent.qml requires the lid to be open before displaying biometric options, ensuring users can always authenticate via password when the sensor is physically inaccessible.

Where does Omarchy store its PAM configuration files?

Omarchy writes service-specific PAM files to /etc/pam.d/, including omarchy-lock-password, omarchy-lock-fingerprint, and modifies existing system files like sudo and polkit-1. The omarchy-apply-lock, omarchy-setup-security-fingerprint, and omarchy-setup-security-fido2 scripts handle these modifications idempotently, creating backups where appropriate and ensuring system stability during hardware configuration changes.

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