Authentication Strategy¶

This document outlines the comprehensive authentication strategy implemented across the infrastructure, focusing on the dual-route approach that balances security for browser access with accessibility for API usage.

Overview¶

The authentication strategy implements a dual-route approach where: - Browser Access: Protected by Authentik OAuth2/OIDC authentication - API Access: Unprotected routes with higher priority for programmatic access

This approach ensures that human users authenticate through a secure SSO system while maintaining API accessibility for automation, monitoring, and integration workflows.

Architecture Principles¶

1. Security by Default¶

All web interfaces are protected by authentication unless explicitly configured otherwise
OAuth2/OIDC provides modern, secure authentication flows
Session management through encrypted cookies with proper domain scoping

2. API Accessibility¶

Critical API endpoints remain accessible without authentication
Higher-priority routes bypass authentication middleware
Maintains compatibility with existing automation and monitoring tools

3. Centralized Management¶

Single authentication provider (Authentik) for all services
Unified user management and access control
Consistent authentication experience across all services

4. Service Independence¶

Services retain their internal authentication mechanisms
API keys and service tokens continue to work as designed
Authentication layer is transparent to service functionality

Implementation Details¶

Traefik Router Priority System¶

The dual-route strategy relies on Traefik's router priority system:

# API Route (Higher Priority)
traefik.http.routers.service-api.priority: 100
traefik.http.routers.service-api.rule: Host(`service.rbnk.uk`) && PathPrefix(`/api/`)
traefik.http.routers.service-api.middlewares: api-access@file

# Browser Route (Default Priority)
traefik.http.routers.service.rule: Host(`service.rbnk.uk`)
traefik.http.routers.service.middlewares: authentik-secured@file

Middleware Chains¶

Protected Browser Access¶

authentik-secured:
  chain:
    middlewares:
      - redirect-to-https
      - authentik

Unprotected API Access¶

api-access:
  chain:
    middlewares:
      - redirect-to-https
      - security-headers

Service Categories¶

Tier 1: Full Protection¶

Services with both browser and API access patterns requiring the dual-route strategy.

Prometheus (`prometheus.rbnk.uk`)¶

Browser Access: Web UI protected by Authentik
API Access: /api/* and /metrics endpoints unprotected
Use Case: Human monitoring via web UI, automated scraping via API

Configuration Example:

labels:
  # Browser protection
  - "traefik.http.routers.prometheus.middlewares=authentik-secured@file"
  # API access
  - "traefik.http.routers.prometheus-api.rule=Host(`prometheus.rbnk.uk`) && (PathPrefix(`/api/`) || PathPrefix(`/metrics`))"
  - "traefik.http.routers.prometheus-api.priority=100"
  - "traefik.http.routers.prometheus-api.middlewares=api-access@file"

LiteLLM (`llm.rbnk.uk`)¶

Browser Access: Management UI protected by Authentik
API Access: OpenAI-compatible API endpoints unprotected
Use Case: Human configuration via web UI, AI applications via API

Configuration Example:

labels:
  # Browser protection
  - "traefik.http.routers.litellm.middlewares=authentik-secured@file"
  # API access
  - "traefik.http.routers.litellm-api.rule=Host(`llm.rbnk.uk`) && (PathPrefix(`/v1/`) || PathPrefix(`/chat/`) || PathPrefix(`/completions`) || PathPrefix(`/models`) || PathPrefix(`/health`))"
  - "traefik.http.routers.litellm-api.priority=100"
  - "traefik.http.routers.litellm-api.middlewares=api-access@file"

Apprise (`apprise.rbnk.uk`)¶

Browser Access: Configuration UI protected by Authentik
API Access: Notification endpoints unprotected
Use Case: Human configuration via web UI, automated notifications via API

Configuration Example:

labels:
  # Browser protection
  - "traefik.http.routers.apprise.middlewares=authentik-secured@file"
  # API access
  - "traefik.http.routers.apprise-api.rule=Host(`apprise.rbnk.uk`) && (PathPrefix(`/notify/`) || PathPrefix(`/json/`) || PathPrefix(`/get/`) || PathPrefix(`/add/`) || PathPrefix(`/del/`) || PathPrefix(`/form/`))"
  - "traefik.http.routers.apprise-api.priority=100"
  - "traefik.http.routers.apprise-api.middlewares=api-access@file"

Tier 2: Browser-Only Protection¶

Services that primarily serve web interfaces with minimal API requirements.

Infrastructure Management¶

Portainer (portainer.rbnk.uk) - Docker management interface
Rclone (rclone.rbnk.uk) - Cloud storage management
Glance (glance.rbnk.uk) - Infrastructure dashboard

Document and Media Services¶

Paperless-AI (paperless-ai.rbnk.uk) - Document management
Metube (metube.rbnk.uk) - YouTube downloader

Configuration Example:

labels:
  - "traefik.http.routers.service.middlewares=authentik-secured@file"

Tier 3: No Authentication¶

Services that handle their own authentication or are intentionally public.

Supabase - Has built-in authentication system
Gitea - Has built-in authentication system
n8n - Has built-in authentication system
AdGuard Home - Has built-in authentication system
Grafana - Has built-in authentication system

Authentication Flow¶

Browser Access Flow¶

Initial Request: User accesses https://service.rbnk.uk
Route Matching: Traefik matches the browser route (lower priority)
Middleware Chain: Request passes through authentik-secured middleware
Authentication Check: Authentik proxy validates authentication
Redirect (if needed): Unauthenticated users redirected to Authentik login
OAuth Flow: User authenticates via Authentik
Session Creation: Authentication cookie set for .rbnk.uk domain
Service Access: User redirected back to original service with valid session

API Access Flow¶

API Request: Client accesses https://service.rbnk.uk/api/endpoint
Route Matching: Traefik matches API route (higher priority)
Middleware Chain: Request passes through api-access middleware
Direct Access: No authentication required, request forwarded to service
Service Response: Service handles request using internal authentication (if any)

Service-Specific Patterns¶

OpenAI-Compatible APIs¶

Services implementing OpenAI-compatible APIs (like LiteLLM) use API key authentication:

# Client authentication via API key
curl -H "Authorization: Bearer sk-1234567890abcdef" \
     https://llm.rbnk.uk/v1/chat/completions

Monitoring and Metrics¶

Monitoring services provide both human and machine interfaces:

# Human access (requires authentication)
https://prometheus.rbnk.uk

# Machine access (no authentication)
curl https://prometheus.rbnk.uk/metrics
curl https://prometheus.rbnk.uk/api/v1/query?query=up

Notification Services¶

Notification APIs remain accessible for automated alerts:

# Automated notification (no authentication)
curl -X POST https://apprise.rbnk.uk/notify/apprise \
     -H "Content-Type: application/json" \
     -d '{"title": "Alert", "body": "System notification"}'

Migration Guide¶

Adding Authentication to Existing Services¶

Identify Service Type:
Browser-only: Use authentik-secured middleware
Browser + API: Implement dual-route strategy
Self-authenticated: No changes needed

Update Docker Compose Labels:

# For browser-only services
labels:
  - "traefik.http.routers.service.middlewares=authentik-secured@file"

# For dual-route services
labels:
  # Browser access
  - "traefik.http.routers.service.middlewares=authentik-secured@file"
  # API access
  - "traefik.http.routers.service-api.rule=Host(`service.rbnk.uk`) && PathPrefix(`/api/`)"
  - "traefik.http.routers.service-api.priority=100"
  - "traefik.http.routers.service-api.middlewares=api-access@file"

Configure Authentik Provider:
Create proxy provider in Authentik UI
Set external host URL
Configure skip path regex for API routes (if applicable)
Test Both Access Patterns:
Verify browser access requires authentication
Confirm API access works without authentication
Test session persistence across subdomains

Removing Authentication¶

To remove authentication from a service:

Update Labels:

# Remove authentication middleware
- "traefik.http.routers.service.middlewares=redirect-to-https@file"

Remove Authentik Provider: Delete provider from Authentik UI
Test Access: Verify service is accessible without authentication

Security Considerations¶

Domain: .rbnk.uk - enables SSO across all subdomains
Secure Flag: Enforced via HTTPS-only configuration
HttpOnly: Prevents client-side cookie access
SameSite: Configured for CSRF protection

API Security¶

Network Level: All traffic encrypted via TLS
Service Level: Services implement their own API authentication
Access Control: API endpoints chosen carefully to minimize exposure
Monitoring: API access logged and monitored

Session Management¶

Timeout: Configurable session timeout in Authentik
Logout: Global logout available from Authentik interface
Token Refresh: Automatic token refresh for active sessions
Revocation: Immediate session revocation through Authentik

Monitoring and Alerting¶

Authentication Metrics¶

Failed Login Attempts: Monitored via Authentik logs
Session Duration: Tracked in Authentik analytics
API vs Browser Traffic: Monitored via Traefik metrics
Service Access Patterns: Analyzed through access logs

Alert Conditions¶

High Failed Login Rate: Potential brute force attack
Authentication Service Down: Impacts all protected services
Certificate Expiration: Breaks OAuth flows
Database Connection Issues: Impacts session storage

Health Checks¶

# Test authentication flow
curl -I https://prometheus.rbnk.uk
# Should return 302 redirect to Authentik

# Test API access
curl -I https://prometheus.rbnk.uk/metrics
# Should return 200 OK

# Test Authentik health
curl -I https://authentik.rbnk.uk
# Should return 200 OK

Troubleshooting¶

Common Issues¶

Authentication Loops¶

Symptom: Endless redirects between service and Authentik
Cause: Incorrect OAuth configuration or cookie domain issues
Solution: Verify AUTHENTIK_HOST_BROWSER and proxy outpost configuration

API Access Blocked¶

Symptom: API requests receive authentication redirects
Cause: Missing or incorrect API route configuration
Solution: Check router priority and PathPrefix matching

Session Not Persisting¶

Symptom: Re-authentication required for each service
Cause: Cookie domain configuration issues
Solution: Verify proxy outpost on separate subdomain with correct cookie domain

Debugging Commands¶

# Check Traefik routes
curl http://localhost:8080/api/http/routers | jq '.[] | select(.rule | contains("service"))'

# Test authentication headers
curl -H "Cookie: authentik_session=..." https://service.rbnk.uk

# Check Authentik logs
docker compose -f authentik/docker-compose.yml logs -f server

Future Improvements¶

Planned Enhancements¶

Multi-Factor Authentication: TOTP/WebAuthn support
API Key Management: Centralized API key authentication
Advanced Policies: Time-based and IP-based access controls
Audit Logging: Comprehensive access auditing
Single Sign-Out: Global logout across all services

Scalability Considerations¶

Load Balancing: Multiple Authentik proxy outposts
Database Scaling: PostgreSQL read replicas for authentication
Cache Optimization: Redis cluster for session storage
Geographic Distribution: Regional authentication endpoints

Best Practices¶

Service Configuration¶

Always use the dual-route pattern for services with APIs
Set appropriate priority values (100+ for API routes)
Test both access patterns during deployment
Document API endpoints that bypass authentication
Monitor access patterns for security anomalies

Security Hygiene¶

Regular token rotation for outpost tokens
Monitor failed authentication attempts
Audit user access permissions regularly
Keep Authentik updated to latest security patches
Backup authentication configuration regularly

Performance Optimization¶

Monitor authentication latency for user experience
Optimize session storage (Redis performance)
Cache authentication responses where possible
Load balance authentication endpoints under high load
Monitor database performance for session storage

Authentication Strategy¶

Overview¶

Architecture Principles¶

1. Security by Default¶

2. API Accessibility¶

3. Centralized Management¶

4. Service Independence¶

Implementation Details¶

Traefik Router Priority System¶

Middleware Chains¶

Protected Browser Access¶

Unprotected API Access¶

Service Categories¶

Tier 1: Full Protection¶

Prometheus (prometheus.rbnk.uk)¶

LiteLLM (llm.rbnk.uk)¶

Apprise (apprise.rbnk.uk)¶

Tier 2: Browser-Only Protection¶

Infrastructure Management¶

Document and Media Services¶

Tier 3: No Authentication¶

Authentication Flow¶

Browser Access Flow¶

API Access Flow¶

Service-Specific Patterns¶

OpenAI-Compatible APIs¶

Monitoring and Metrics¶

Notification Services¶

Migration Guide¶

Adding Authentication to Existing Services¶

Removing Authentication¶

Security Considerations¶

Cookie Security¶

API Security¶

Session Management¶

Monitoring and Alerting¶

Authentication Metrics¶

Alert Conditions¶

Health Checks¶

Troubleshooting¶

Common Issues¶

Authentication Loops¶

API Access Blocked¶

Session Not Persisting¶

Debugging Commands¶

Future Improvements¶

Planned Enhancements¶

Scalability Considerations¶

Best Practices¶

Service Configuration¶

Security Hygiene¶

Performance Optimization¶

Prometheus (`prometheus.rbnk.uk`)¶

LiteLLM (`llm.rbnk.uk`)¶

Apprise (`apprise.rbnk.uk`)¶