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

shashank — Tue, 31 Mar 2026 07:38:55 +0000

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:

Face detection (RetinaFace)
Face alignment (landmark-based)
Embedding generation (ArcFace, 512-dim)
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.

DEV Community: shashank