Building a Face Authentication System for Linux (Using PAM, systemd, and ONNX)

Linux still lacks a reliable, native biometric authentication system.

While platforms like Windows and macOS have tightly integrated face authentication, Linux users typically rely on passwords — or experimental tools that often break under real-world conditions.

I wanted something:

• fully offline
• predictable under PAM
• extensible and debuggable

So I built AstraLock.

shekh-2810 / AstraLock

AstraLock is a lightweight face-authentication system designed for Linux. It replaces legacy camera pipelines with modern deep-learning models, optimized preprocessing, and a clean, modular architecture. The goal is simple: reliable face-based login on Linux without the sluggishness, low-light failures, or angle sensitivity seen in older tools.

AstraLock

AstraLock is a Linux biometric authentication system that enables face-based login through PAM and systemd, designed to be offline, auditable, and hackable, offering a native Linux alternative to projects like Howdy and closed platforms such as Windows Hello without cloud dependencies.

It runs a local daemon that performs facial verification and integrates directly with system authentication flows such as sudo, login, display managers, and polkit.

What AstraLock Is

• A system daemon that performs face verification

• A PAM module (pam_facelock.so) for system authentication

• A CLI tool for enrollment, verification, and testing

• A local-only LBPH model (no cloud, no network)

No external services. No telemetry. No vendor lock-in.

Features

• 🔐PAM authentication (login, sudo, polkit, display managers)
• 🧠Offline facial recognition (LBPH, OpenCV)
• ⚙️systemd-managed daemon lifecycle
• 📷 Webcam support via OpenCV
• 🧪Built-in testing via pamtester
• Simple CLI for users and admins

---

Architecture

…

View on GitHub

The Problem with Existing Approaches

Most existing solutions (like Howdy) work — until they don’t.

Common issues:

• PAM inconsistencies across sudo, login, and display managers
• unreliable camera handling
• fragile integration with system components
• limited control over the authentication pipeline

The biggest issue wasn’t the ML part — it was system integration.

---

Design Goals

Before writing code, I defined strict constraints:

• No cloud dependencies
• No telemetry
• Deterministic PAM behavior
• Clean separation between authentication logic and ML
• Works across CLI and GUI authentication flows

---

High-Level Architecture

Instead of embedding everything inside PAM, I separated concerns:

Application (sudo / login / GUI)
        ↓
       PAM
        ↓
pam_facelock.so
        ↓
facelockd (systemd service)
        ↓
UNIX socket IPC
        ↓
Face recognition pipeline

Why this design?

PAM modules should stay minimal and predictable.

Heavy operations like:

• camera access
• model inference
• image processing

are handled by a separate daemon.

This avoids blocking PAM and improves reliability.

---

Recognition Pipeline

The pipeline uses modern ONNX-based models:

1. Face detection (RetinaFace)
2. Face alignment (landmark-based)
3. Embedding generation (ArcFace, 512-dim)
4. Cosine similarity for matching

Everything runs locally.

No external APIs. No network calls.

---

Key Challenges

1. PAM Behavior is Subtle

The biggest issue was handling:

• auth sufficient vs required
• fallback to password authentication
• inconsistent behavior across services

Small changes in PAM configuration can completely change outcomes.

---

2. Display Managers Are Inconsistent

GDM, SDDM, and others:

• handle authentication differently
• sometimes retry unexpectedly
• may break assumptions about flow

This required testing across environments.

---

3. Camera Reliability

Accessing /dev/video* sounds simple — but:

• permissions vary
• devices differ
• latency can affect authentication timing

---

4. Avoiding Lockouts

Biometric authentication is probabilistic.

So:

• password fallback is always preserved
• PAM is configured as sufficient, not exclusive

---

Current Capabilities

• Works with sudo, login, and GUI prompts (polkit)
• Fully offline inference
• Local model storage per user
• systemd-managed daemon
• CLI for enrollment and verification

---

Security Considerations

This is not meant to replace passwords entirely.

Important points:

• biometric matching is probabilistic
• spoofing is a real concern
• fallback authentication is required

The system is designed for:

convenience + controlled risk, not absolute security

---

What I Learned

• System integration is harder than ML
• PAM is powerful but unforgiving
• Reliability matters more than accuracy
• Simplicity in design reduces failure cases

---

Looking for Feedback

I’m particularly interested in input on:

• PAM edge cases in real-world deployments
• failure modes I might be missing
• biometric authentication tradeoffs on Linux
• ways to improve reliability without sacrificing usability

---

Project

AstraLock is open source and still evolving.

If you’ve worked with PAM, Linux auth, or system-level tooling, I’d appreciate your perspective.