Quartz 4

03 - Authelia & Biometric Passkey SSO

4 min read

Authelia & Biometric Passkey SSO

Overview

Authelia is the identity provider and gatekeeper for our private services. It replaces clumsy passwords with native WebAuthn Biometric Passkeys (Touch ID, Face ID, Android Biometrics, YubiKey), providing instant, single-touch access across all ganeshr.me applications.

1. What is Single Sign-On (SSO)?

In a traditional homelab without SSO, every single service has its own login screen, username, and password. If you host 5 tools, you manage 5 accounts.

With Authelia SSO:

  1. You authenticate once at https://auth.ganeshr.me.
  2. Authelia issues an encrypted, secure session cookie scoped to your entire domain (.ganeshr.me).
  3. Whenever you open hq.ganeshr.me, wealth.ganeshr.me, or cockpit.ganeshr.me, Caddy detects your active cookie and lets you straight in—no second login required.
sequenceDiagram
    autonumber
    actor User as User Device (FaceID / TouchID)
    participant Caddy as Caddy Proxy
    participant Authelia as Authelia SSO
    participant App as Homepage / Wealthfolio

    User->>Caddy: GET https://hq.ganeshr.me
    Caddy->>Authelia: Forward Auth: Has valid session cookie?
    Authelia-->>Caddy: 401 Unauthorized (No Cookie)
    Caddy-->>User: 302 Redirect to auth.ganeshr.me
    User->>Authelia: Biometric Passkey Touch (WebAuthn)
    Authelia-->>User: Issue encrypted cookie (*.ganeshr.me) & redirect
    User->>Caddy: GET https://hq.ganeshr.me (with Cookie)
    Caddy->>Authelia: Forward Auth: Has valid session cookie?
    Authelia-->>Caddy: 200 OK + User Headers (Remote-User: ganesh)
    Caddy->>App: Proxy request with headers
    App-->>User: Render dashboard

2. The Passkey Breakthrough: Single-Touch 2FA

Traditional Two-Factor Authentication (2FA) is tedious:

  1. Type a master password.
  2. Open an authenticator app (Google Authenticator / Aegis).
  3. Copy a 6-digit TOTP code before the 30-second timer expires.

How Our Passkey Configuration Works:

In /opt/vaultwarden/authelia/configuration.yml:

webauthn:
  disable: false
  enable_passkey_login: true
  experimental_enable_passkey_uv_two_factors: true
  experimental_enable_passkey_upgrade: true
  selection_criteria:
    discoverability: preferred
    user_verification: preferred
  • User Verification (UV): When you touch your fingerprint sensor or scan Face ID, the device hardware cryptographically certifies that the authorized user was physically verified.
  • Single-Touch 2FA (experimental_enable_passkey_uv_two_factors): Authelia treats your physical device (“something you have”) + biometric check (“something you are”) as satisfying both factors simultaneously in one touch.

Phishing Resistance

Passkeys are mathematically bound to the domain auth.ganeshr.me. Even if a malicious attacker created an exact visual replica of your login page on another domain, your browser would refuse to release your cryptographic credentials.

3. Session Persistence & Security Settings

Authelia is tuned for high convenience without compromising security:

  • Session Lifetime (expiration: 1M): Once you log in on your personal phone or laptop, your session remains active for 1 full month.
  • Inactivity Window (inactivity: 14d): If you don’t use any homelab service for 14 consecutive days, the session automatically terminates for security.
  • Cookie Domain: Scoped to ganeshr.me, allowing seamless cross-subdomain transitions.
  • Brute-Force Regulation:
    • Maximum retries: 5 attempts
    • Find time: 120 seconds
    • Ban time: 5 minutes lockout if triggered

4. Access Control Rules

The policy engine dictates which services require authentication:

access_control:
  default_policy: deny
  rules:
    - domain: ['hq.ganeshr.me', 'cockpit.ganeshr.me', 'wealth.ganeshr.me']
      policy: two_factor

Why is vault.ganeshr.me Excluded?

Vaultwarden is intentionally omitted from Authelia’s access rules.

  1. Vaultwarden uses client-side zero-knowledge encryption with its own master key.
  2. Official Bitwarden mobile apps (iOS/Android) and browser extensions do not support external HTTP forward-auth redirects and would fail to sync if Authelia intervened.

5. Storage & Key File Locations

  • Configuration File: /opt/vaultwarden/authelia/configuration.yml
  • Local User File: /opt/vaultwarden/authelia/users_database.yml
  • Passkey & WebAuthn Database: /opt/vaultwarden/authelia/db.sqlite3
  • Notification Log: /opt/vaultwarden/authelia/notification.txt

Cryptographic Keys:

Authelia relies on three unique 256-bit cryptographic secrets defined in configuration.yml:

  • identity_validation.reset_password.jwt_secret
  • session.secret
  • storage.encryption_key

6. Daily Operations & Emergency Runbook

Check Live Authentication Logs

To see logins and passkey challenges in real time:

sudo docker logs -f authelia

How to Register an Additional Device / Passkey

  1. Open https://auth.ganeshr.me on the new device (e.g. your iPad or work laptop).
  2. If already logged in, navigate to Account Settings / Security Keys.
  3. Click Register New Security Key / Passkey.
  4. Touch the biometric prompt on your new device.
  5. Both devices can now unlock your homelab independently.

Emergency Lockout: “What if I lost my passkey device?”

If you lose your registered device, you can fall back to the master administrative password:

  1. Open https://auth.ganeshr.me.
  2. Instead of tapping the passkey prompt, choose Sign in with username and password.
  3. Enter username ganesh and the master admin password stored in your Bitwarden vault.
  4. Authelia will write a temporary verification link to /opt/vaultwarden/authelia/notification.txt.
  5. Read the link via SSH: 
    sudo cat /opt/vaultwarden/authelia/notification.txt
  6. Open the link in your browser to approve the session and register a replacement device.

7. Next Steps & Related Links

Graph View

Backlinks