Zitadel Authentication Plugin

Optional plugin that adds Single Sign-On (SSO) authentication to Dryade via Zitadel.

Enables login with Google, GitHub, Microsoft, and other identity providers.

Quick Start

1. Start Zitadel

cd docker/zitadel
cp .env.example .env
# Edit .env with secure credentials
docker compose up -d

2. Configure Zitadel Project

1. Access Zitadel console at http://localhost:8080
2. Create a project and API application
3. Note the Project ID

3. Enable Plugin in Dryade

Add to your .env:

DRYADE_ZITADEL_ENABLED=true
DRYADE_ZITADEL_ISSUER=http://localhost:8080
DRYADE_ZITADEL_PROJECT_ID=your-project-id

4. (Optional) Install Zitadel Library

For full token validation support:

pip install fastapi-zitadel-auth

Features

• SSO Providers: Google, GitHub, Microsoft, Apple, GitLab, SAML
• User Sync: External users automatically created/linked in local database
• Role Mapping: Zitadel roles mapped to local user roles
• Graceful Fallback: App works fully without Zitadel

API Endpoints

When enabled, the plugin adds these endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/v1/auth/sso/providers | GET | List available SSO providers | | /api/v1/auth/sso/login/{provider} | GET | Get Zitadel login URL | | /api/v1/auth/sso/callback | POST | Handle SSO callback | | /api/v1/auth/sso/status | GET | Check SSO availability |

Configuration

| Variable | Default | Description | |----------|---------|-------------| | DRYADE_ZITADEL_ENABLED | false | Enable Zitadel SSO | | DRYADE_ZITADEL_ISSUER | "" | Zitadel server URL | | DRYADE_ZITADEL_PROJECT_ID | "" | Zitadel project ID |

User Sync Behavior

When a user authenticates via Zitadel:

1. New User: Created with is_external=True, no password
2. Existing Email: Linked to Zitadel (is_external set to True)
3. Role Sync: Admin role from Zitadel grants admin in Dryade

External users:

• Cannot use password login
• Must use SSO for authentication
• Are auto-verified (Zitadel handles verification)

Troubleshooting

Plugin Not Enabling

1. Check DRYADE_ZITADEL_ENABLED=true in .env
2. Verify DRYADE_ZITADEL_ISSUER and DRYADE_ZITADEL_PROJECT_ID are set
3. Check logs for initialization messages

SSO Returns 503

{"detail": "SSO not available - Zitadel plugin not enabled"}

This means:

• Zitadel is disabled or not configured
• fastapi-zitadel-auth is not installed
• Zitadel server is not reachable

Users Not Syncing

Check that:

• Zitadel token has email claim
• Database is accessible
• User model supports external auth fields

Architecture

Frontend
    │
    ▼ (1) Click "Login with Google"
FastAPI ──────────────────────────────────┐
    │                                      │
    ▼ (2) Redirect to Zitadel             │
Zitadel ◄────────────────────────────────┘
    │
    ▼ (3) OAuth flow with Google
Google IDP
    │
    ▼ (4) Return to Zitadel with auth
Zitadel
    │
    ▼ (5) Redirect to callback with token
FastAPI
    │
    ├── (6a) Sync user to PostgreSQL
    │
    └── (6b) Return local JWT tokens

Development

Testing Without Zitadel

The plugin is designed to be optional:

# Plugin initializes but stays disabled
plugin = ZitadelAuthPlugin()
plugin.startup()
assert not plugin.is_enabled  # OK - no error

App continues to work with local auth

Running Tests

pytest tests/unit/test_zitadel_plugin.py -v

Mock Zitadel Token

For testing user sync:

mock_token = {
    "sub": "zitadel-user-id",
    "email": "user@example.com",
    "name": "Test User",
    "roles": ["member"],
}
sync = ZitadelUserSync(db)
user = sync.get_or_create_user(mock_token)

Security Notes

• Never expose Zitadel master key
• Use HTTPS in production
• Configure proper CORS for Zitadel
• Review Zitadel's security documentation