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](https://docs.goauthentik.io/install-config/install/docker-compose/)

### Container-Level Resource Limits

Based on real-world deployment optimization (from [TEK Online case study](https://www.tekonline.com.au/diagnosing-and-fixing-high-cpu-usage-in-authentik-stack/)), recommended resource limits for single-user deployments:

#### PostgreSQL Database
```yaml
resources:
  limits:
    cpus: '1'
    memory: 1G
  reservations:
    cpus: '0.5'
    memory: 512M
```

#### Redis Cache
```yaml
resources:
  limits:
    cpus: '0.5'
    memory: 512M
  reservations:
    cpus: '0.2'
    memory: 256M
```

#### Authentik Server
```yaml
resources:
  limits:
    cpus: '1'
    memory: 1G
  reservations:
    cpus: '0.5'
    memory: 512M
```

#### Authentik Worker
```yaml
resources:
  limits:
    cpus: '1'
    memory: 1G
  reservations:
    cpus: '0.5'
    memory: 512M
```

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

```yaml
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](https://version-2024-2.goauthentik.io/docs/outposts/)

### 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](https://notes.catdad.science/2023/03/02/self-hosting-chronicles-plex-oidc.html)

---

## 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):**
```bash
# 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](https://docs.goauthentik.io/docs/sys-mgmt/ops/backup-restore)

#### 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](https://docs.goauthentik.io/core/architecture/)

### 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](https://docs.goauthentik.io/docs/install-config/upgrade)

### Configuration Storage

**S3 External Storage (Optional):**
```yaml
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](https://docs.goauthentik.io/install-config/configuration/)

---

## 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](https://docs.goauthentik.io/sys-mgmt/service-accounts/)

### Token Creation Methods

#### Method 1: Bootstrap Token (Automated Install)

Set during initial deployment for the default `akadmin` user:

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

**Kubernetes/Helm Example:**
```yaml
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](https://docs.goauthentik.io/install-config/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](https://github.com/goauthentik/authentik/issues/7707) requests environment variable support for initial API token generation
- GitHub Issue [#12882](https://github.com/goauthentik/authentik/issues/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:**
```bash
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](https://docs.goauthentik.io/add-secure-apps/providers/oauth2/machine_to_machine)

### 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):**
```python
# 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](https://docs.goauthentik.io/customize/policies/expression/)

### 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](https://docs.goauthentik.io/add-secure-apps/flows-stages/stages)

### Advanced Expression Policy Functions

**Available Helper Functions:**
```python
# 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:**
```python
# Enforce MFA for superuser/admin accounts
if context['pending_user'].is_superuser:
    return True
return False
```

**Or by Username:**
```python
# 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](https://docs.goauthentik.io/install-config/install/docker-compose/)
- [Authentik Backup and Restore](https://docs.goauthentik.io/docs/sys-mgmt/ops/backup-restore)
- [Authentik Service Accounts](https://docs.goauthentik.io/sys-mgmt/service-accounts/)
- [Authentik Expression Policies](https://docs.goauthentik.io/customize/policies/expression/)
- [Authentik Automated Install](https://docs.goauthentik.io/install-config/automated-install/)
- [TEK Online: Diagnosing High CPU Usage](https://www.tekonline.com.au/diagnosing-and-fixing-high-cpu-usage-in-authentik-stack/)