ai-tax-agent/docs/SSO Guide.md

Authentik SSO Configuration for AI Tax Agent

This directory contains the configuration for Authentik SSO integration with the AI Tax Agent system.

Overview

Authentik provides:

• Single Sign-On (SSO) for all services
• ForwardAuth middleware for Traefik
• OIDC/OAuth2 providers for applications
• Role-based access control (RBAC)
• User and group management

Architecture

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   User Browser  │───▶│   Traefik    │───▶│   Application   │
└─────────────────┘    └──────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────┐
                       │ Authentik    │
                       │ ForwardAuth  │
                       └──────────────┘

Services

Core Authentik Services

1. authentik-db: PostgreSQL database for Authentik
2. authentik-redis: Redis cache for sessions
3. authentik-server: Main Authentik server
4. authentik-worker: Background task worker
5. authentik-outpost: ForwardAuth proxy

Integration Points

• Traefik: Uses ForwardAuth middleware
• Grafana: OIDC authentication
• API Services: JWT token validation
• Review Portal: NextAuth.js integration

User Groups & Roles

Group	Description	Permissions
Administrators	System administrators	Full access to all services
Tax Reviewers	Review extracted data	Access to review portal, read-only API
Accountants	Firm accountants	Access to client data, forms
Clients	End clients	Limited access to own data

Applications

1. AI Tax Agent API

• Client ID: ai-tax-agent-api
• Type: OIDC/OAuth2
• Scopes: openid, profile, email, roles
• Redirect URI: https://api.local.lan/auth/callback

2. Grafana

• Client ID: grafana
• Type: OIDC/OAuth2
• Scopes: openid, profile, email
• Redirect URI: https://grafana.local.lan/login/generic_oauth

3. UI Review (ForwardAuth)

• Provider Type: Proxy Provider (ForwardAuth)
• External Host: https://review.local.lan
• Internal Host: http://ui-review:3030
• Mode: forward_single
• Authentication: Via Traefik ForwardAuth middleware

Setup Instructions

1. Generate Secrets

make generate-secrets

2. Deploy Infrastructure

make deploy-infra

3. Initial Authentik Setup

1. Open https://auth.local.lan in your browser
2. Complete the initial setup wizard
3. Create admin user with email admin@local.lan
4. Set a secure password

4. Configure Applications

# Set API token from Authentik admin interface
export AUTHENTIK_API_TOKEN="your-api-token-here"
make setup-authentik

5. Verify Setup

• Access Authentik admin: https://auth.local.lan
• Test API authentication: https://api.local.lan/docs
• Check Grafana SSO: https://grafana.local.lan

Configuration Files

bootstrap.yaml

Initial configuration for:

• User groups
• OIDC providers
• Applications
• Policies

exported-config.yaml

UI Review Integration Blueprint - Automated configuration for UI Review ForwardAuth integration:

• Proxy Provider configuration
• Application setup
• Outpost provider assignment

To apply this configuration:

# Apply UI Review integration
docker-compose -f docker-compose.local.yml exec authentik-server ak apply_blueprint /blueprints/exported-config.yaml

custom-templates/

Custom login/logout templates (optional)

media/

Uploaded media files (logos, etc.)

Environment Variables

Variable	Description	Default
AUTHENTIK_SECRET_KEY	Encryption key	changeme
AUTHENTIK_OUTPOST_TOKEN	Outpost authentication	changeme
AUTHENTIK_DB_PASSWORD	Database password	authentik
DOMAIN	Base domain	local

Security Considerations

Production Deployment

1. Change all default passwords
2. Use strong secret keys (50+ characters)
3. Enable HTTPS with valid certificates
4. Configure proper CORS origins
5. Set up backup for Authentik database
6. Enable audit logging

Network Security

• Authentik services run on backend network only
• Only Traefik has access to frontend network
• Database and Redis are internal only

Token Security

• JWT tokens include user roles and tenant ID
• Tokens are validated by each service
• Short token expiry (1 hour) with refresh

Troubleshooting

Common Issues

1. Authentik not accessible

   # Check service status
   docker-compose logs authentik-server
   
   # Verify network connectivity
   docker network ls | grep ai-tax-agent
   

2. ForwardAuth not working

   # Check outpost logs
   docker-compose logs authentik-outpost
   
   # Verify Traefik configuration
   docker-compose logs traefik
   

3. OIDC authentication failing

   # Check provider configuration
   curl -s https://auth.local.lan/.well-known/openid_configuration
   
   # Verify redirect URIs
   # Check client secrets
   

Debug Mode

Enable debug logging:

# In docker-compose.local.lan.yml
AUTHENTIK_LOG_LEVEL: debug

API Integration

Getting User Information

Services receive user information via headers:

ForwardAuth Headers (UI Review):

• x-authentik-username: Username
• x-authentik-email: Email address
• x-authentik-groups: Comma-separated groups
• x-authentik-name: Full name
• x-authentik-uid: User ID

Legacy Headers (Other Services):

• X-Authenticated-User: Username
• X-Authenticated-Email: Email address
• X-Authenticated-Groups: Comma-separated groups
• Authorization: JWT Bearer token

Example FastAPI Integration

from libs.security import AuthenticationHeaders

@app.get("/protected")
async def protected_endpoint(request: Request):
    auth = AuthenticationHeaders(request)

    if not auth.has_role("Tax Reviewers"):
        raise HTTPException(403, "Insufficient permissions")

    return {"user": auth.authenticated_user}

Monitoring

Health Checks

• Authentik server: https://auth.local.lan/-/health/ready/
• Outpost: http://authentik-outpost:9000/outpost.goauthentik.io/ping

Metrics

• Prometheus metrics: https://auth.local.lan/metrics
• Grafana dashboard: "Authentik Overview"

Backup & Recovery

Database Backup

# Backup Authentik database
docker exec authentik-db pg_dump -U authentik authentik > authentik_backup.sql

# Restore
docker exec -i authentik-db psql -U authentik authentik < authentik_backup.sql

Configuration Backup

• Export flows and providers from admin interface
• Backup bootstrap.yaml and custom templates
• Store secrets securely (Vault, etc.)

Support

For issues with Authentik configuration:

1. Check the official documentation
2. Review logs in docker-compose logs authentik-server
3. Verify network connectivity and DNS resolution
4. Check Traefik middleware configuration