ai-tax-agent/docs/authentik-sso-setup-guide.md

Authentik SSO Automated Setup Guide

This guide explains how to use the automated Authentik SSO setup for the AI Tax Agent platform.

Overview

The AI Tax Agent platform uses Authentik for Single Sign-On (SSO) with automated configuration through blueprints. This provides:

• Automated application configuration using Authentik blueprints
• Secure secret generation for all OAuth clients
• Role-based access control with predefined user groups
• ForwardAuth integration with Traefik for seamless authentication

Quick Start

1. Deploy Infrastructure

# Generate secure secrets and deploy infrastructure
make generate-secrets
make run

2. Complete Initial Setup

Option A: Automated (recommended)

make setup-sso

Option B: Manual Steps

# Step 1: Complete initial Authentik setup manually
# Open https://auth.local/if/flow/initial-setup/
# Use credentials: admin@local / admin123

# Step 2: Get API token and import configuration
make complete-authentik-setup
make setup-authentik

3. Verify Setup

make verify

All services should redirect to Authentik for authentication.

Detailed Process

Step 1: Infrastructure Deployment

# Generate secure secrets
make generate-secrets

# Deploy all services
make run

This will:

• Generate secure random secrets for all services
• Deploy Authentik with the latest version (2025.8.3)
• Mount the bootstrap blueprint for automatic configuration

Step 2: Initial Authentik Setup

The system will detect if initial setup is needed and guide you through it:

make complete-authentik-setup

Manual Setup (if automated fails):

1. Open https://auth.local/if/flow/initial-setup/
2. Use these credentials:
   • Email: admin@local
   • Password: admin123
3. Complete the setup wizard

Step 3: Blueprint Import

make setup-authentik

This will automatically:

• Import the blueprint configuration
• Create user groups (Administrators, Tax Reviewers, Accountants, Clients)
• Configure OAuth2 providers for API and Grafana
• Set up ForwardAuth proxy for Traefik integration
• Create applications with proper redirect URIs

Configuration Details

User Groups Created

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 Configured

1. AI Tax Agent API

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

2. Grafana

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

3. ForwardAuth Proxy

• Type: Proxy Provider
• Mode: forward_single
• External Host: https://api.local
• Skip Paths: /health, /metrics, /docs, /openapi.json

Environment Variables

The setup automatically configures these environment variables:

# Authentik Configuration
AUTHENTIK_SECRET_KEY=<generated-50-char-secret>
AUTHENTIK_BOOTSTRAP_EMAIL=admin@local
AUTHENTIK_BOOTSTRAP_PASSWORD=admin123
AUTHENTIK_BOOTSTRAP_TOKEN=<auto-generated-api-token>

# OAuth Client Secrets
AUTHENTIK_API_CLIENT_SECRET=<generated-32-char-secret>
AUTHENTIK_GRAFANA_CLIENT_SECRET=<generated-32-char-secret>

Verification

1. Check Service Status

make status

All Authentik services should show as "healthy":

• authentik-server
• authentik-worker
• authentik-outpost
• authentik-db
• authentik-redis

2. Test Authentication

make verify

Should show:

• ✅ Authentik (https://auth.local) -> 200

3. Access URLs

• Authentik Admin: https://auth.local
• API Gateway: https://api.local (redirects to Authentik)
• Grafana: https://grafana.local (SSO enabled)
• Review Portal: https://review.local (SSO enabled)

Troubleshooting

Common Issues

1. Initial Setup Page Still Shows

# Check if setup completed properly
curl -k --resolve 'auth.local:443:127.0.0.1' -I https://auth.local/if/flow/initial-setup/

If you get HTTP 200, setup is still needed. Complete it manually.

2. Blueprint Import Failed

# Check Authentik logs
make logs-service SERVICE=authentik-server

# Re-run blueprint import
make setup-authentik

3. API Token Issues

# Manually create API token
# 1. Login to https://auth.local
# 2. Go to Admin Interface > Tokens
# 3. Create new token
# 4. Update .env file:
echo "AUTHENTIK_BOOTSTRAP_TOKEN=your-token-here" >> infra/compose/.env

4. Services Not Redirecting to Authentik

# Check Traefik configuration
make logs-service SERVICE=traefik

# Restart Authentik components
make restart-authentik

Debug Mode

Enable debug logging:

# Add to docker-compose.local.yml
AUTHENTIK_LOG_LEVEL: debug

Security Considerations

Production Deployment

1. Change default passwords immediately after setup
2. Use strong secret keys (automatically generated)
3. Enable HTTPS with valid certificates
4. Configure proper CORS origins
5. Set up backup for Authentik database
6. Enable audit logging

Secret Management

• All secrets are automatically generated with sufficient entropy
• Client secrets are stored in environment variables
• API tokens should be rotated regularly
• Never commit .env file to version control

Integration Examples

FastAPI Service 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}

Grafana Configuration

Grafana is automatically configured with these settings:

[auth.generic_oauth]
enabled = true
name = Authentik
client_id = grafana
client_secret = <auto-generated>
scopes = openid profile email
auth_url = https://auth.local/application/o/authorize/
token_url = https://auth.local/application/o/token/
api_url = https://auth.local/application/o/userinfo/

Support

For issues with the automated setup:

1. Check the logs: make logs-service SERVICE=authentik-server
2. Verify network connectivity: make verify
3. Review the blueprint file: infra/compose/authentik/bootstrap.yaml
4. Check Traefik routing: make logs-service SERVICE=traefik

For Authentik-specific issues, refer to the official documentation.