pangolin/.tasks/artifacts/authentik-research.md

Authentik Best Practices for Single-User/Single-Admin Deployments

Research Date: 2026-01-20 Task: RESEARCH-002 Purpose: Comprehensive research on Authentik deployment strategies for minimal single-user/admin environments

---

1. Minimal Resource Configuration

Host Requirements

• Minimum Specification: 2 CPU cores and 2 GB RAM (official recommendation)
• Source: Authentik Docker Compose Installation Documentation

Container-Level Resource Limits

Based on real-world deployment optimization (from TEK Online case study), recommended resource limits for single-user deployments:

PostgreSQL Database

resources:
  limits:
    cpus: '1'
    memory: 1G
  reservations:
    cpus: '0.5'
    memory: 512M

Redis Cache

resources:
  limits:
    cpus: '0.5'
    memory: 512M
  reservations:
    cpus: '0.2'
    memory: 256M

Authentik Server

resources:
  limits:
    cpus: '1'
    memory: 1G
  reservations:
    cpus: '0.5'
    memory: 512M

Authentik Worker

resources:
  limits:
    cpus: '1'
    memory: 1G
  reservations:
    cpus: '0.5'
    memory: 512M

Kubernetes Deployments

For Kubernetes-based deployments, configure resource limits via JSON patches:

kubernetes_json_patches:
  deployment:
    - op: add
      path: "/spec/template/spec/containers/0/resources"
      value:
        requests:
          cpu: 2000m
          memory: 2000Mi
        limits:
          cpu: 2000m
          memory: 2000Mi

Source: Authentik Outpost Configuration

Minimal Viable Configuration Notes

• VPS Testing: One user reported running Authentik on a free tier with 1 shared vCPU and 256MB shared memory, but this proved insufficient and caused OOM kills
• Recommended Minimum: 512MB dedicated memory per component (Postgres and Authentik server) to avoid stability issues
• Source: Self-hosting Chronicles Blog

---

2. Backup Strategies

Official Backup Components

Authentik backups consist of two critical components:

2.1 PostgreSQL Database Backup

Critical Importance: The database stores ALL persistent data including:

• User accounts and credentials
• Policies and configurations
• Application settings
• Flow definitions
• Provider configurations

Backup Methods:

• Use PostgreSQL native tools:
  • pg_dump for single database dumps
  • pg_dumpall for complete cluster dumps
  • Continuous archiving for point-in-time recovery

Best Practice Example (from Kubernetes upgrade guide):

# Connect to PostgreSQL pod
kubectl exec -it authentik-postgresql-0 -- /bin/bash

# Create dump in pod's data directory
pg_dump -U authentik_user -d authentik_db > /bitnami/postgresql/authentik_backup.sql

# CRITICAL: Copy dump outside the pod
kubectl cp authentik-postgresql-0:/bitnami/postgresql/authentik_backup.sql ./authentik_backup_$(date +%Y%m%d).sql

Important Exclusions:

• Exclude system databases: template0 and template1

Source: Authentik Backup and Restore Documentation

2.2 Static Directory Backups

Required Directories:

1. /media Directory

   • Contains: Application icons, flow backgrounds, uploaded files
   • Only required if NOT using S3 external storage
   • If using S3: Use AWS S3 Sync utility for backups instead

2. /certs Directory

   • Contains: TLS certificates
   • Required for SSL/TLS functionality

Docker Volume Persistence:

• PostgreSQL data: /var/lib/postgresql/data
• Media files: /media
• Certificates: /certs

Source: Authentik Architecture Documentation

Backup Automation Strategy

Recommended Approach (from community discussions):

1. Automate PostgreSQL dumps using cron or systemd timers
2. Back up Docker volumes containing media/certs
3. Store backups in off-site location (follow 3-2-1 rule)
4. Test restore procedures regularly

Pre-Upgrade Requirement:

• ALWAYS backup PostgreSQL database before upgrades
• Reason: Authentik does not support downgrades
• Source: Authentik Upgrade Documentation

Configuration Storage

S3 External Storage (Optional):

AUTHENTIK_STORAGE__MEDIA__BACKEND=s3
AUTHENTIK_STORAGE__MEDIA__S3__BUCKET_NAME=your-bucket

Benefits for Single-User Deployments:

• Reduces local storage requirements
• Simplifies media file backups
• Enables cross-region redundancy

Source: Authentik Configuration Documentation

---

3. API Token Management for Service Accounts

Service Account Overview

Purpose: Machine-to-machine authentication and automation

• Ideal for: Scripts, CI/CD pipelines, infrastructure-as-code (Terraform)
• Authentication method: HTTP Basic Authentication with token

Source: Authentik Service Accounts Documentation

Token Creation Methods

Method 1: Bootstrap Token (Automated Install)

Set during initial deployment for the default akadmin user:

# Environment variable
AUTHENTIK_BOOTSTRAP_TOKEN=your-secure-token-here

Kubernetes/Helm Example:

bootstrap_token: test
# Or reference from secret:
secretRef: authentik-bootstrap-secret

Benefits:

• Enables fully automated deployments
• No manual UI interaction required
• Perfect for infrastructure-as-code workflows

Source: Authentik Automated Install

Method 2: Manual Token Creation via Admin UI

1. Navigate to Directory > Tokens and App passwords
2. Create new token with Intent: API Token
3. Default lifespan: 30 minutes (configurable)

Token Properties:

• Can be configured as expiring or non-expiring
• Supports auto-rotation
• User-specific permissions apply

Method 3: Programmatic Token Generation

Current Limitation (as of 2024):

• GitHub Issue #7707 requests environment variable support for initial API token generation
• GitHub Issue #12882 discusses programmatic bearer token creation post-bootstrap

Workaround for Automation:

• Use AUTHENTIK_BOOTSTRAP_TOKEN for initial setup
• Subsequent tokens can be created via API using the bootstrap token

Machine-to-Machine (M2M) Authentication

OAuth 2.0 Client Credentials Grant:

• Uses grant_type=client_credentials
• Authentication via service account username + app password token
• Returns signed JWT access token

Automatic Service Account Creation:

• Pass configured client_secret during token request
• Authentik auto-generates service account
• Naming scheme: <provider-name>-service-account

Example Token Request:

curl -X POST https://authentik.example.com/application/o/token/ \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "username=service-account-name" \
  -d "password=app-password-token"

Source: Machine-to-Machine Authentication

Best Practices for Single-Admin Deployments

1. Bootstrap Token: Set AUTHENTIK_BOOTSTRAP_TOKEN during initial deployment
2. Service Accounts: Create dedicated service accounts for each automation task
3. Token Rotation: Enable auto-rotation for long-lived tokens
4. Least Privilege: Assign minimal required permissions to service accounts
5. Audit Logging: Monitor API token usage via Authentik's built-in logging

---

4. MFA Enforcement Policies

Single-Admin MFA Strategy

For single-user/single-admin deployments, MFA enforcement can be achieved through Expression Policies bound to authenticator validation stages.

Expression Policy Implementation

Concept: Use Python-based expression policies to conditionally enforce MFA for specific users.

Example Policy (User-Specific MFA):

# Enforce MFA only for admin user
if context['pending_user'].username == "admin":
    return True  # Enforce MFA stage
return False  # Skip MFA stage for other users

Policy Binding:

1. Create authenticator validation stage in authentication flow
2. Create expression policy with above code
3. Bind policy to the MFA stage binding
4. Result: Only "admin" user sees MFA prompt

Source: Expression Policies Documentation

User/Group Binding Approach

Alternative Method: Bind users directly to stage bindings

Process:

1. Create MFA prompt stage in authentication flow
2. Bind stage to flow
3. In stage binding settings, specify which users/groups must complete the stage
4. Result: Only bound users see the MFA prompt

Advantages:

• No code required
• Simpler for single-admin scenarios
• GUI-based configuration

Source: Stages Documentation

Advanced Expression Policy Functions

Available Helper Functions:

# Check group membership
ak_is_group_member(user, group_name="admins")

# Check if user has authenticator enrolled
ak_user_has_authenticator(user, device_type="totp")

# Get user by username
ak_user_by(username="admin")

Context Variables:

• context['pending_user'] - User attempting authentication
• context['request'] - HTTP request object
• context['flow_plan'] - Current flow execution plan

Recommended MFA Policy for Single-Admin

Strict Admin-Only MFA:

# Enforce MFA for superuser/admin accounts
if context['pending_user'].is_superuser:
    return True
return False

Or by Username:

# Enforce MFA for specific admin username
admin_usernames = ["olaf", "admin", "root"]
if context['pending_user'].username in admin_usernames:
    return True
return False

Best Practice: Always enforce MFA for accounts with administrative privileges, even in single-user deployments, to protect against credential compromise.

---

5. Additional Considerations for Single-User Deployments

Security Hardening

• Enable MFA for admin account (see section 4)
• Use strong, unique passwords (consider password manager)
• Regularly update Authentik (with pre-upgrade backups)
• Enable audit logging and review periodically

Monitoring and Maintenance

• Set up health check endpoints monitoring
• Configure email notifications for critical events
• Schedule regular backup verifications (test restore)
• Monitor resource usage (CPU/memory) for optimization

Disaster Recovery

• Document restore procedures
• Store backup credentials securely (separate from production)
• Test full recovery process at least quarterly
• Maintain off-site backup copies (3-2-1 rule)

Network Security

• Use reverse proxy (Traefik, nginx) with TLS termination
• Implement rate limiting for authentication endpoints
• Consider IP allowlisting for admin interface
• Use internal Docker networks for database/Redis

---

Summary

For single-user/single-admin Authentik deployments:

1. Resources: Minimum 2 CPU cores, 2 GB RAM host; set container limits (1GB memory, 1 CPU per service)
2. Backups: Automate PostgreSQL dumps + backup /media and /certs volumes; test restores regularly
3. API Tokens: Use AUTHENTIK_BOOTSTRAP_TOKEN for automation; create service accounts for scripts
4. MFA: Implement expression policies or stage bindings to enforce MFA for admin account only

These practices ensure a secure, maintainable, and resource-efficient Authentik deployment suitable for personal/small-scale use cases.

---

References

• Authentik Docker Compose Installation
• Authentik Backup and Restore
• Authentik Service Accounts
• Authentik Expression Policies
• Authentik Automated Install
• TEK Online: Diagnosing High CPU Usage