olaf/pangolin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: cleaned project structure

Browse Source 
- Consolidated documentation from Ralph Loop iterations
- Archived 20+ outdated/superseded files to .archive/
- Kept essential docs: OIDC integration, mobile setup, quick start
- Added operational scripts for health monitoring and backup
- Research artifacts preserved in .tasks/artifacts/

Current state:
- 3 VPS sites (fry, proton, photon) ONLINE in Pangolin
- brn-home site pending for local services (Jellyfin, etc.)
- Mobile access configuration pending

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Olaf
2026-01-21 06:15:04 +00:00
commit b428721b07
17 changed files with 5749 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

399
.tasks/artifacts/authentik-research.md Normal file
View File

@@ -0,0 +1,399 @@
# 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/)