Initial commit

docs/SSO Guide.md

@@ -0,0 +1,296 @@
+# 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
+
+```bash
+make generate-secrets
+```
+
+### 2. Deploy Infrastructure
+
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+# 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**
+
+   ```bash
+   # Check service status
+   docker-compose logs authentik-server
+
+   # Verify network connectivity
+   docker network ls | grep ai-tax-agent
+   ```
+
+2. **ForwardAuth not working**
+
+   ```bash
+   # Check outpost logs
+   docker-compose logs authentik-outpost
+
+   # Verify Traefik configuration
+   docker-compose logs traefik
+   ```
+
+3. **OIDC authentication failing**
+
+   ```bash
+   # Check provider configuration
+   curl -s https://auth.local.lan/.well-known/openid_configuration
+
+   # Verify redirect URIs
+   # Check client secrets
+   ```
+
+### Debug Mode
+
+Enable debug logging:
+
+```bash
+# 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
+
+```python
+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
+
+```bash
+# 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](https://goauthentik.io/docs/)
+2. Review logs in `docker-compose logs authentik-server`
+3. Verify network connectivity and DNS resolution
+4. Check Traefik middleware configuration