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

```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