Skip to content

authelia

Metadata

Field Value
Service authelia
Purpose Shared identity, SSO, and forward-auth service for protected applications
Criticality Tier 1
Owner Platform / Identity owner
Clusters homelab, local, jls
Namespace auth
Exposure internet
Stateful yes
Backup class snapshot
RPO / RTO Daily backup target, 1 to 4 hours to restore authentication service
Last reviewed 2026-06-29

1. Service Overview

Authelia provides shared authentication for internet-facing services and acts as a critical dependency for the protected Traefik access path.

Summary

If Authelia fails, protected applications may become inaccessible or lose their expected authentication enforcement.

Dependencies

Dependency Type Why it matters
Traefik ingress Forward-auth integration and public routing
MariaDB database Stores sessions and service state
Mail delivery notification Required for password reset and identity workflows

2. Architecture Diagram

[User]
  -> [Traefik]
  -> [Authelia]
  -> [MariaDB]
  -> [Protected application]

3. Deployment Specifications

Item Value
Source path authelia/base and authelia/overlays/*
Deployment model Fleet-managed Kustomize overlays
Namespace auth
Workload kind Deployment plus MariaDB StatefulSet
Chart or image version Authelia 4.39.20
Config files fleet.yaml, base/kustomization.yaml, overlays/homelab, overlays/local, overlays/jls

Cluster mapping

Cluster Overlay path Notes
homelab authelia/overlays/homelab Homelab-specific target customization
local authelia/overlays/local Unified local-cluster deployment
jls authelia/overlays/jls JLS-specific target customization

4. Configuration Guide

Environment variables

Variable Source Purpose Secret?
Authelia runtime settings Overlay ConfigMaps and Secret file mounts Identity, SMTP, session, storage, and MFA behavior mixed

ConfigMaps

Resource Path Purpose
Overlay-managed config authelia/base and authelia/overlays/* Runtime configuration and per-cluster customization

Secrets management

  • Secret name: authelia in the auth namespace
  • Required keys: identity validation JWT secret, session encryption key, storage encryption key, storage password, Duo integration key, Duo secret key, SMTP password, and MariaDB root password
  • Source of truth: existing overlay Secret manifests until a repository-wide secret mechanism is chosen
  • Rotation trigger: identity provider updates, SMTP changes, or incident response
  • Recovery note: restore all secrets before bringing the service back online
  • Audit note: the file authentication user database is still tracked in the overlay ConfigMaps as existing repository state; moving it to an out-of-band Secret requires an operator-approved secret migration and rotation plan.

Authentication and MFA

  • TOTP is the default second-factor method for enrolled users.
  • Duo push remains enabled as a phone-push second-factor method.
  • WebAuthn remains enabled as an additional supported second factor.
  • Trusted internal, VPN, and selected source networks bypass protected wildcard domains for services that cannot support 2FA.
  • Other protected wildcard traffic requires two_factor; the Authelia portal host and CORS preflight requests also bypass policy.

5. Access Protocols

Path URL or endpoint Audience Auth TLS terminates at
Internal Services inside the auth namespace and forward-auth endpoints Cluster workloads namespace RBAC Traefik / Authelia
External local https://auth.mutana.fr End users and operators Authelia auth flows with TOTP MFA Traefik
External homelab https://auth.home.mutana.fr End users and operators Authelia auth flows with TOTP MFA Traefik
External jls https://auth.mutana.site End users and operators Authelia auth flows with TOTP MFA Traefik

6. Operations and Observability

  • Primary health indicators: Authelia pod Ready, MariaDB healthy, and successful forward-auth checks from Traefik.
  • Dashboards or alerts: shared monitoring plus ingress and auth logs.
  • Log locations: Authelia application logs and MariaDB pod logs in the auth namespace.
  • Known failure modes: broken DB connectivity, bad secret material, SMTP issues, or ingress middleware misconfiguration.
  • Resource profile: Authelia requests 100m CPU and 128Mi memory with a 512Mi memory limit, except local uses a 1Gi memory limit for extra Argon2 headroom. MariaDB requests 50m CPU and 128Mi memory with a 512Mi memory limit.

7. Backup and Recovery Notes

  • Backup method: MariaDB backup plus secret backup and PVC snapshot.
  • Restore prerequisites: DB credentials, session secrets, SMTP settings, and Traefik middleware integration.
  • Database engine note: PostgreSQL is preferred for future supported database work, but this deployment remains on MariaDB until a separate data migration and rollback plan is approved.
  • Related runbook: ../runbooks/authelia.md

8. Release and Change Notes

  • Current deployed app version: Authelia 4.39.20.
  • Current chart version: not used for the active Kustomize deployment.
  • Last significant change: Authelia was updated to 4.39.20, default MFA moved to TOTP, Duo push was kept active, trusted-network bypass was preserved, and unmatched wildcard protected traffic requires two-factor authentication.
  • Rollback reference: previous overlay revision in Git.