A revolutionary implementation of the Kerberos authentication protocol that eliminates passwords, achieves high availability, and embraces modern cloud-native architecture. This project addresses the fundamental weaknesses of traditional Kerberos implementations through innovative design patterns and contemporary technologies.
This project implements a passwordless, highly available, and microservice-based Kerberos authentication system. We replace traditional password-based authentication with PKINIT (Public Key Cryptography for Initial Authentication), implement Primary-Replica KDC architecture for zero downtime, and modernize the entire stack with API-driven provisioning and a React-based user interface.
- True Passwordless Authentication: PKINIT implementation using X.509 certificates
- High Availability: Primary-Replica KDC architecture with automatic failover
- Microservice Architecture: Dockerized, API-driven, cloud-native design
- Multi-Device Support: Zero-trust device approval workflow
- Modern UI: React frontend with WebCrypto API integration
- Architecture Overview
- Technology Stack
- Quick Start
- Service Components
- Security Features
- Authentication Flow
- Multi-Device Workflow
- Database Schema
- Configuration
- Development Guide
- API Documentation
- Troubleshooting
- Contributing
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ React Client โ โ Python Client โ โ Mobile App โ
โโโโโโโโโโโฌโโโโโโโโ โโโโโโโโโโโฌโโโโโโโโ โโโโโโโโโโโฌโโโโโโโโ
โ โ โ
โโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโ
โ CA Server โ โ Certificate Authority
โ (Port 5000) โ Issues X.509 Certificates
โโโโโโโโโโโฌโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโ
โ Provisioning โ โ Database Writer
โ Server โ Manages User Provisioning
โ (Port 5001) โ & Replica Synchronization
โโโโโโโโโโโฌโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโ
โ โ โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Primary KDC โ โ Replica KDC โ
โ (Port 8888) โ โ (Port 8889) โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ โ โ
โโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโ
โ Service Server โ โ Protected Application
โ (Port 6001) โ Validates Service Tickets
โโโโโโโโโโโโโโโโโโโ
| Traditional Kerberos Problem | Our Solution | Benefits |
|---|---|---|
| Password Vulnerability | PKINIT with X.509 certificates | Eliminates phishing, credential stuffing, offline attacks |
| Single Point of Failure | Primary-Replica KDC architecture | 100% uptime, automatic failover |
| Monolithic Architecture | Microservices with Docker | Cloud-native, scalable, maintainable |
| CLI-only Administration | RESTful APIs + React UI | Modern UX, programmatic integration |
- Language: Python 3.9+
- Web Framework: Flask (RESTful APIs)
- Authentication Protocol: WebSockets (KDC communication)
- Cryptography:
cryptographylibrary (RSA, AES-GCM, X.509, SHA-256) - Database: SQLite (ACID-compliant, file-based)
- Containerization: Docker & Docker Compose
- Framework: React 18 with TypeScript
- Styling: Tailwind CSS
- Routing: React Router v6
- Cryptography: Web Crypto API (browser-native)
- Certificate Handling: PKI.js for X.509 operations
- Build Tool: Vite
- Orchestration: Docker Compose
- Networking: Private Docker bridge network (
kerberos-net) - Storage: Named Docker volumes for persistence
- Health Checks: Built-in container health monitoring
- Docker & Docker Compose
- Node.js 18+ (for frontend development)
- Git
git clone https://github.com/yourusername/kerberos.git
cd kerberosCreate a .env file in the project root:
# Generate secrets with: openssl rand -base64 32
TGS_SECRET_KEY_B64=your_tgs_secret_key_base64
SERVICE_SECRET_KEY_B64=your_service_secret_key_base64
CA_PASSWORD=your_ca_password
INTERNAL_API_KEY=your_internal_api_key
# Optional configurations
REALM=MYKERBEROSPROJECT
TGT_LIFETIME_SECONDS=21600
SERVICE_TICKET_LIFETIME_SECONDS=300
TIMESTAMP_WINDOW_SECONDS=300# Start all services
docker-compose up -d
# Verify all services are healthy
docker-compose ps- React Frontend: http://localhost:3000
- CA Server API: http://localhost:5000
- Primary KDC: WebSocket on localhost:8888
- Replica KDC: WebSocket on localhost:8889
- Service Server: WebSocket on localhost:6001
- Navigate to http://localhost:3000
- Click "Sign Up" to create a new account
- Generate keys and certificate in-browser
- Login and access protected services
# Run the integrated test client
docker exec -it ca_server python -m client.mainPort: 5000 | Role: Identity Issuer
- Issues X.509 certificates for user authentication
- Manages Certificate Signing Requests (CSRs)
- Handles multi-device approval workflow
- Maintains certificate trust store
Key Endpoints:
GET /ca-cert- Download CA public certificatePOST /submit-csr- Submit certificate requestPOST /poll-pending-requests- Check for device approvals (authenticated)POST /approve-request- Approve/reject device requests (authenticated)
Primary Port: 8888 | Replica Port: 8889
Primary KDC:
- Initializes and manages the master authentication database
- Handles AS-REQ (Authentication Server requests)
- Processes TGS-REQ (Ticket Granting Server requests)
- Provides service discovery via LIST_SERVICES
Replica KDC:
- Read-only clone for high availability
- Automatic failover target
- Synchronized via Provisioning Server
Protocol Support:
- WebSocket-based communication
- AS-REQ: PKINIT authentication with certificate validation
- TGS-REQ: Service ticket generation
- LIST_SERVICES: Available service enumeration
Port: 5001 | Role: Database Writer & Replication Manager
- Only service with write access to KDC database
- Creates new user accounts and devices
- Synchronizes Primary โ Replica database
- Protected by
INTERNAL_API_KEY
Key Endpoints:
POST /provision-new-user- Create new user accountPOST /add-device- Add device to existing userPOST /sync-replica- Trigger manual database synchronization
Port: 6001 | Role: Protected Application
- Validates Kerberos service tickets
- Demonstrates the AP-REQ protocol flow
- Returns protected data upon successful authentication
- Implements replay attack prevention
Port: 3000 | Role: User Interface
- Browser-based key generation (WebCrypto API)
- Certificate request submission
- Multi-device approval interface
- Service access dashboard
- Private Key Generation: 2048-bit RSA keys generated client-side
- Certificate-based Authentication: X.509 certificates replace passwords
- Proof of Possession: Digital signatures prove private key ownership
- No Secrets in Database: Only public key fingerprints stored
- Encryption: AES-256-GCM for symmetric encryption
- Key Exchange: RSA-OAEP for asymmetric encryption
- Signatures: RSA-PSS with SHA-256
- Certificate Validation: Full X.509 chain verification
- Timestamp Windows: 5-minute freshness requirement
- Nonce Generation: Cryptographically secure randomness
- Session Keys: Unique per authentication session
- Ticket Expiration: Configurable lifetime limits
- Docker Network Isolation: Private
kerberos-netbridge - API Key Protection: Internal service authentication
- Certificate Pinning: CA certificate validation
- WebSocket Security: Encrypted communication channels
Client KDC
| |
| 1. Generate timestamp |
| 2. Sign {principal,timestamp} |
| with private key |
| |
| AS-REQ{cert, principal, |
| timestamp, signature} |
|------------------------------>|
| | 3. Verify certificate chain
| | 4. Validate signature
| | 5. Check fingerprint in DB
| | 6. Validate timestamp
| | 7. Generate session key & TGT
| |
| {encrypted_session_key, |
| encrypted_tgt} |
|<------------------------------|
Client KDC
| |
| 1. Create authenticator |
| 2. Encrypt with session key |
| |
| TGS-REQ{tgt, authenticator, |
| service_principal} |
|------------------------------>|
| | 3. Decrypt TGT with TGS key
| | 4. Decrypt authenticator
| | 5. Validate timestamp & principal
| | 6. Generate service ticket
| |
| {service_ticket, |
| encrypted_service_session_key}|
|<------------------------------|
Client Service Server
| |
| 1. Create authenticator |
| 2. Encrypt with service |
| session key |
| |
| AP-REQ{service_ticket, |
| authenticator} |
|--------------------------->|
| | 3. Decrypt ticket with service key
| | 4. Decrypt authenticator
| | 5. Validate timestamp & principal
| |
| Protected resource data |
|<---------------------------|
Our system implements a "zero-trust" multi-device approval process inspired by modern applications like Signal and WhatsApp.
-
Device Registration Request
# User attempts login from new device POST /submit-csr { "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----...", "is_signup": false }
-
Pending Approval Response
{ "status": "pending_approval", "request_id": "uuid-string", "message": "Request received. Please approve from a trusted device." } -
Trusted Device Polling
# Existing device checks for pending requests POST /poll-pending-requests Headers: { "X-Client-Cert": "base64_certificate", "X-Client-Signature": "base64_signature", "X-Client-Timestamp": "ISO8601_timestamp" }
-
Approval Decision
POST /approve-request { "request_id": "uuid-string", "action": "approve" # or "reject" } -
New Device Polling
# New device polls for approval status GET /check-request-status/{request_id} -
Certificate Delivery
{ "status": "approved", "certificate": "-----BEGIN CERTIFICATE-----..." }
-- Certificate issuance log
CREATE TABLE certificates (
serial_number INTEGER PRIMARY KEY,
subject_name TEXT NOT NULL,
principal_name TEXT NOT NULL,
status TEXT NOT NULL, -- 'trusted', 'pending', 'revoked'
issued_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
expires_at TIMESTAMP NOT NULL,
fingerprint TEXT NOT NULL UNIQUE
);
-- Multi-device approval queue
CREATE TABLE pending_requests (
request_id TEXT PRIMARY KEY,
principal_name TEXT NOT NULL,
new_csr_pem TEXT NOT NULL,
new_cert_subject TEXT NOT NULL,
fingerprint TEXT NOT NULL UNIQUE,
status TEXT NOT NULL DEFAULT 'pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);-- Master user accounts
CREATE TABLE users (
user_id INTEGER PRIMARY KEY AUTOINCREMENT,
principal_name TEXT NOT NULL UNIQUE
);
-- Trusted devices per user
CREATE TABLE devices (
device_id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL,
cert_fingerprint TEXT NOT NULL UNIQUE,
cert_subject TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'trusted',
FOREIGN KEY (user_id) REFERENCES users (user_id)
);
-- Service cryptographic keys
CREATE TABLE service_keys (
principal_name TEXT PRIMARY KEY NOT NULL,
secret_key_b64 TEXT NOT NULL
);
-- Service metadata
CREATE TABLE services (
service_id INTEGER PRIMARY KEY AUTOINCREMENT,
principal_name TEXT UNIQUE NOT NULL,
service_name TEXT NOT NULL,
service_url TEXT,
description TEXT,
FOREIGN KEY (principal_name) REFERENCES service_keys (principal_name)
);| Variable | Description | Required | Default |
|---|---|---|---|
TGS_SECRET_KEY_B64 |
TGS service encryption key (base64) | โ | - |
SERVICE_SECRET_KEY_B64 |
Service server encryption key (base64) | โ | - |
CA_PASSWORD |
CA private key password | โ | - |
INTERNAL_API_KEY |
Inter-service authentication key | โ | - |
REALM |
Kerberos realm name | โ | MYKERBEROSPROJECT |
TGT_LIFETIME_SECONDS |
Ticket-Granting Ticket lifetime | โ | 21600 (6 hours) |
SERVICE_TICKET_LIFETIME_SECONDS |
Service ticket lifetime | โ | 300 (5 minutes) |
TIMESTAMP_WINDOW_SECONDS |
Replay attack prevention window | โ | 300 (5 minutes) |
Create frontend/.env:
VITE_CA_URL=http://localhost:5000
VITE_KDC_PRIMARY_URL=ws://localhost:8888
VITE_KDC_REPLICA_URL=ws://localhost:8889
VITE_SERVICE_URL=ws://localhost:6001For production deployment, create docker-compose.override.yml:
version: "3.8"
services:
ca-server:
environment:
- FLASK_ENV=production
restart: unless-stopped
primary-kdc:
deploy:
resources:
limits:
memory: 512M
reservations:
memory: 256M-
Backend Development
# Install Python dependencies pip install -r requirements.txt # Run individual services python -m ca_server.main python -m kdc_server.main --role primary python -m provisioning_server.main python -m service_server.main
-
Frontend Development
cd frontend npm install npm run dev
-
View Logs
# All services docker-compose logs -f # Specific service docker-compose logs -f ca-server
-
Database Inspection
# Connect to CA database docker exec -it ca_server sqlite3 /app/data/ca.db # Connect to KDC database docker exec -it primary_kdc sqlite3 /app/db/primary/kdc.db
-
Network Testing
# Test WebSocket connections websocat ws://localhost:8888 {"type": "health_check"}
GET /ca-cert
Accept: application/x-pem-filePOST /submit-csr
Content-Type: application/json
{
"csr_pem": "-----BEGIN CERTIFICATE REQUEST-----...",
"is_signup": true
}POST /poll-pending-requests
X-Client-Cert: base64_encoded_certificate
X-Client-Signature: base64_encoded_signature
X-Client-Timestamp: 2024-01-01T12:00:00Z{
"type": "AS_REQ",
"cert_pem": "-----BEGIN CERTIFICATE-----...",
"principal": "user@REALM",
"timestamp": "2024-01-01T12:00:00Z",
"signed_data": "base64_signature"
}{
"type": "TGS_REQ",
"tgt": "base64_encrypted_tgt",
"authenticator": "base64_encrypted_authenticator",
"service_principal": "host/service.server@REALM"
}{
"type": "LIST_SERVICES"
}{
"type": "AP_REQ",
"service_ticket": "base64_encrypted_ticket",
"authenticator": "base64_encrypted_authenticator"
}# Symptom: "Certificate signature is invalid"
# Solution: Verify CA certificate is properly loaded
docker exec -it primary_kdc ls -la /app/data/ca_cert.pem# Symptom: "Database file not found"
# Solution: Check volume mounts and initialization
docker-compose exec primary-kdc ls -la /app/db/primary/# Symptom: Connection refused on KDC ports
# Solution: Check service health and port mapping
docker-compose ps
curl -f http://localhost:8888 || echo "KDC not responding"# Symptom: "WebCrypto not available"
# Solution: Ensure HTTPS or localhost context
# Check browser console for detailed errorsAll services include built-in health checks:
# Check overall system health
docker-compose ps
# Individual service health
docker exec ca_server python -c "import requests; print(requests.get('http://localhost:5000/ca-cert').status_code)"# Resource usage
docker stats
# Database performance
docker exec primary_kdc sqlite3 /app/db/primary/kdc.db ".timer on" ".stats on" "SELECT COUNT(*) FROM users;"- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Submit a Pull Request
- Python: Follow PEP 8, use type hints
- TypeScript: Follow ESLint configuration
- Docker: Multi-stage builds, minimal base images
- Documentation: Update README for new features
This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: Check this README and inline code comments
- Issues: Report bugs via GitHub Issues
- Discussions: Join our GitHub Discussions for questions
- Hardware Security Module (HSM) integration
- Certificate Revocation List (CRL) support
- OAuth 2.0 / OpenID Connect integration
- Kubernetes deployment manifests
- WebAuthn compatibility layer
- Mobile application (React Native)
- Metrics and monitoring (Prometheus/Grafana)
- Audit logging and compliance reporting
Built with โค๏ธ by the Modern Kerberos Team
Revolutionizing authentication, one certificate at a time.