Authentication and Access Control Strategy¶

Status: Implemented with Authentik (2026-01-03) Implementation: See Authentik Application Documentation

Overview¶

Robust Single Sign-On (SSO) solution with group-based access control, multi-factor authentication, and easy user management for family, friends, and business access.

Current Implementation (2026-01-03)¶

Authentik SSO has been successfully deployed as the primary authentication provider for the homelab cluster.

What's Live:

Authentik 2025.10.3 deployed to production cluster
Forward Authentication (ForwardAuth) with Traefik
Domain-level session management (.skaggsfamily.us)
CloudNativePG PostgreSQL backend
7 applications protected with SSO authentication

Migration from Authelia:

Completed: 2026-01-03
Reason: Persistent session timeout issues with Authelia
Result: Session management working correctly with 4-hour inactivity timeout

For operational details, configuration, and troubleshooting, see the Authentik application documentation.

Current Situation Analysis¶

Previous Setup (Lessons Learned)¶

Authentik + Traefik: Worked but was complex and poorly understood
Cisco Duo MFA: Effective security but integration was fragile
Configuration complexity: Difficult to modify or troubleshoot
Single point of failure: When cluster went down, lost all access controls

Requirements for New System¶

Maintainable: Clear documentation and understanding
Scalable: Easy to add users and groups
Resilient: Backup configurations and recovery procedures
Multi-tenant: Support family, friends, and business users
Secure: MFA integration with existing Cisco Duo account

Recommended Architecture¶

Option 1: Authentik (Improved Implementation)¶

Why reconsider Authentik¶

Mature, well-documented platform
Excellent group and policy management
Strong OIDC/SAML support
Active community and development
Previous experience (even if incomplete)

Improvements for maintainability¶

Comprehensive documentation of all configurations
Backup/restore procedures for all settings
Staged deployment with testing procedures
Clear group and access policies

Option 2: Keycloak¶

Alternative enterprise solution¶

Red Hat backed, very stable
Excellent admin UI
Strong LDAP/Active Directory integration
Comprehensive audit logging
More complex but more powerful

Option 3: Authelia¶

Lightweight alternative¶

Simpler configuration
File-based user management
Good for smaller deployments
Less overhead but fewer features

User and Group Strategy¶

User Categories¶

```text Family Members: ├── Adults (full access to family services) ├── Children (restricted access, parental controls) └── Extended family (limited access to shared resources)

Friends: ├── Close friends (access to entertainment services) ├── Casual friends (guest WiFi and basic services) └── Business associates (professional services only)

Business: ├── Customers (website and order management) ├── Contractors (limited business tool access) └── Vendors (specific service access)

System Accounts: ├── Service accounts (inter-service authentication) ├── Monitoring accounts (read-only access) └── Backup accounts (automated systems) ```text

```text

Group Structure¶

```text

```text Core Groups: ├── family-admin: Full administrative access ├── family-member: Standard family services ├── family-child: Restricted family access ├── friend-trusted: Entertainment and shared services ├── friend-guest: Basic guest access ├── business-admin: Business service administration ├── business-user: Customer and client access └── service-account: Automated system access

Service-Specific Groups: ├── grafana-admin: Monitoring administration ├── grafana-viewer: Read-only monitoring access ├── media-admin: Media server management ├── media-user: Media consumption access ├── vaultwarden-admin: Password manager administration ├── vaultwarden-user: Password manager access ├── wordpress-admin: Website administration └── wordpress-editor: Content editing access ```text

```text

Access Control Policies¶

Service Access Matrix¶

```text

```text Service | Family | Friends | Business | Public

------------------|--------|---------|----------|------- VaultWarden | ✓ | ✗ | ✗ | ✗ Media Server | ✓ | ✓ | ✗ | ✗ WordPress Admin | ✓ | ✗ | ✓ | ✗ WordPress Public | ✓ | ✓ | ✓ | ✓ Grafana Admin | ✓ | ✗ | ✗ | ✗ Grafana Viewer | ✓ | ✗ | ✓ | ✗ File Sharing | ✓ | ✓ (lim) | ✗ | ✗ Gaming Services | ✓ | ✓ | ✗ | ✗ Business Tools | ✓ | ✗ | ✓ | ✗ ```text

```text

Cisco Duo MFA Integration¶

MFA Requirements by Service¶

```text

```text Critical Services (Always MFA): ├── VaultWarden (password manager) ├── Administrative interfaces ├── Financial/business applications └── External access to internal services

Important Services (MFA for external access): ├── Media server (external access only) ├── File sharing (external access only) ├── Monitoring dashboards (external access) └── WordPress admin (external access)

Low-Risk Services (Optional MFA): ├── Internal network access ├── Guest services └── Public content consumption ```text

```text

Duo Integration Configuration¶

```yaml

Authentik Duo Integration¶

duo_integration: api_hostname: "api-xxxxxxxx.duosecurity.com" integration_key: "from_duo_admin_panel" secret_key: "from_duo_admin_panel"

# MFA policies policies:

- name: "critical-services"

  require_mfa: true

  allowed_methods: ["push", "phone", "sms"]

- name: "external-access"

  require_mfa: true

  bypass_internal: true

- name: "family-internal"

  require_mfa: false

  trusted_networks: ["172.16.100.0/24", "172.16.103.0/24"]

```text

Implementation Architecture¶

Deployment Strategy¶

```text

```text Kubernetes Deployment: ├── Authentik Server (primary authentication) ├── Authentik Worker (background tasks) ├── PostgreSQL Database (user and configuration data) ├── Redis Cache (session and token storage) └── Backup CronJob (configuration and database backups)

Integration Points: ├── Traefik/Nginx Ingress (forward auth middleware) ├── Application OIDC clients (direct integration) ├── Legacy HTTP Basic Auth (simple applications) └── API authentication (service-to-service) ```text

```text

High Availability Considerations¶

```text

```text Database: ├── PostgreSQL with backup to Apollo Freezer ├── Regular configuration exports └── Point-in-time recovery capability

Application: ├── Multiple Authentik pods for redundancy ├── Redis clustering for session persistence └── Health checks and automatic restart

Network: ├── Multiple ingress paths ├── Internal service mesh communication └── Fallback authentication methods ```text

```text

Configuration Management¶

Infrastructure as Code¶

```yaml

Helm values for Authentik deployment¶

authentik: replicas: 2 database: type: postgresql host: postgres.auth.svc.cluster.local

redis: host: redis.auth.svc.cluster.local

ingress: enabled: true hostname: auth.yourdomain.com tls: enabled: true secretName: auth-tls-cert

# Duo integration env: AUTHENTIK_STAGES_AUTHENTICATOR_DUO_CLIENT_ID: "duo-client-id" AUTHENTIK_STAGES_AUTHENTICATOR_DUO_CLIENT_SECRET: "duo-secret" ```text

```text

Backup Strategy¶

```yaml

Backup CronJob for Authentik¶

apiVersion: batch/v1 kind: CronJob metadata: name: authentik-backup spec: schedule: "0 2 * * *" # Daily at 2 AM jobTemplate: spec: template: spec: containers:

      - name: backup

        image: postgres:15

        command:

        - /bin/bash
        - -c
        - |

          # Database backup

          pg_dump authentik > /backup/authentik-$(date +%Y%m%d).sql

          # Configuration export via API
          curl -H "Authorization: Bearer $AUTHENTIK_TOKEN" \
               https://auth.domain.com/api/v3/admin/settings/ \
               > /backup/authentik-config-$(date +%Y%m%d).json
        volumeMounts:

        - name: backup-storage

          mountPath: /backup

      volumes:

      - name: backup-storage

        nfs:

          server: apollo.local
          path: /mnt/disks/Freezer/k8s-backups/authentik

```text

User Management Procedures¶

Adding New Users¶

```bash

Family member workflow¶

Create user in Authentik admin panel
Add to appropriate groups (family-member, service-specific)
Configure MFA requirements based on access level
Send invitation with setup instructions
Document in family IT records

Friend access workflow¶

Create guest user account
Add to friend-trusted or friend-guest group
Set account expiration if temporary
Provide limited service access instructions
Monitor usage and adjust as needed

Business user workflow¶

Create business user account
Add to business-specific groups
Require MFA for all business services
Set up audit logging for compliance
Document for business records

```text

Group Management¶

```yaml

Group policy examples¶

family-admin: permissions:

- authentik_admin
- grafana_admin
- media_admin
- all_services_access

mfa_required: true

session_timeout: 24h

family-member: permissions:

- media_user
- vaultwarden_user
- file_sharing_user

mfa_required: false # internal network only

session_timeout: 7d

friend-trusted: permissions:

- media_user
- gaming_access

mfa_required: true # external access

session_timeout: 4h restrictions:

- no_admin_access
- bandwidth_limited

```text

Security Considerations¶

Network Security¶

Internal vs External Access: Different MFA requirements
IP Allowlisting: Trusted networks for family devices
Rate Limiting: Prevent brute force attacks
Session Management: Appropriate timeouts by user type

Audit and Compliance¶

Access Logging: All authentication events logged
Failed Login Monitoring: Alert on suspicious activity
Regular Access Reviews: Quarterly user and group audits
Configuration Changes: All admin changes logged and backed up

Emergency Access¶

Break Glass Procedures: Emergency admin access methods
Offline Authentication: Local account fallbacks
Recovery Procedures: Steps to restore authentication after failures

Integration Examples¶

Traefik Forward Auth¶

```yaml

Traefik middleware for Authentik¶

apiVersion: traefik.containo.us/v1alpha1 kind: Middleware metadata: name: authentik-forward-auth spec: forwardAuth: address: http://authentik.auth.svc.cluster.local/outpost.goauthentik.io/auth/traefik trustForwardHeader: true authResponseHeaders:

  - X-authentik-username
  - X-authentik-groups
  - X-authentik-email

```text

Application OIDC Integration¶

```yaml

VaultWarden OIDC configuration¶

vaultwarden: env: SSO_ENABLED: "true" SSO_ONLY: "false" SSO_AUTHORITY: "https://auth.domain.com/application/o/vaultwarden/" SSO_CLIENT_ID: "vaultwarden-client-id" SSO_CLIENT_SECRET: "vaultwarden-client-secret" ```text

```text

Monitoring and Alerting¶

Authentication Metrics¶

```yaml

Prometheus alerts for authentication¶

alert: AuthenticationDown

expr: up{job="authentik"} == 0

for: 30s labels: severity: critical annotations: summary: "Authentication service is down"

alert: HighFailedLogins

expr: rate(authentik_failed_logins_total[5m]) > 5

for: 2m labels: severity: warning annotations: summary: "High rate of failed login attempts"

alert: DuoMFAFailure

expr: rate(authentik_duo_failures_total[5m]) > 0

for: 1m labels: severity: high annotations: summary: "Duo MFA integration issues detected" ```text

```text

Benefits of This Approach¶

Operational Benefits¶

Single sign-on: Users authenticate once for all services
Centralized management: One place to manage all users and access
Audit trail: Complete logging of all authentication events
Scalable: Easy to add new services and users

Security Benefits¶

MFA enforcement: Duo integration for sensitive services
Principle of least privilege: Group-based access control
Session management: Appropriate timeouts and controls
Attack surface reduction: Single, hardened authentication point

Family IT Benefits¶

Reduced password fatigue: SSO reduces password management
Easy guest access: Temporary accounts for friends
Granular control: Different access levels for different users
Self-service: Users can manage some of their own settings

Authentication and Access Control Strategy¶

Overview¶

Current Implementation (2026-01-03)¶

Current Situation Analysis¶

Previous Setup (Lessons Learned)¶

Requirements for New System¶

Recommended Architecture¶

Option 1: Authentik (Improved Implementation)¶

Why reconsider Authentik¶

Improvements for maintainability¶

Option 2: Keycloak¶

Alternative enterprise solution¶

Option 3: Authelia¶

Lightweight alternative¶

Recommended Solution: Authentik (Enhanced)¶

Why Authentik Makes Sense¶

User and Group Strategy¶

User Categories¶

Group Structure¶

Access Control Policies¶

Service Access Matrix¶

Cisco Duo MFA Integration¶

MFA Requirements by Service¶

Duo Integration Configuration¶

Authentik Duo Integration¶

Implementation Architecture¶

Deployment Strategy¶

High Availability Considerations¶

Configuration Management¶

Infrastructure as Code¶

Helm values for Authentik deployment¶

Backup Strategy¶

Backup CronJob for Authentik¶

User Management Procedures¶

Adding New Users¶

Family member workflow¶

Friend access workflow¶

Business user workflow¶

Group Management¶

Group policy examples¶

Security Considerations¶

Network Security¶

Audit and Compliance¶

Emergency Access¶

Integration Examples¶

Traefik Forward Auth¶

Traefik middleware for Authentik¶

Application OIDC Integration¶

VaultWarden OIDC configuration¶

Monitoring and Alerting¶

Authentication Metrics¶

Prometheus alerts for authentication¶

Benefits of This Approach¶

Operational Benefits¶

Security Benefits¶

Family IT Benefits¶

This authentication strategy provides enterprise-grade security with family-friendly usability and maintainable configuration¶