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

> Discover how Omarchy secures user authentication using Linux PAM, Polkit, and hardware security keys like FIDO2 for passwords, fingerprints, and sudo access.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-19

---

**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.

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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

```bash

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

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.