tokn

OAuth2/OIDC and JWT authentication infrastructure demonstration in Rust.

Overview

This workspace demonstrates authentication patterns with:

• oauth2-client (port 8081) - Demo application using OAuth2 authentication
• oauth2-server (port 8082) - OAuth2 authorization server implementation
• jwt-service (port 8083) - Standalone JWT token service

---

Prerequisites

• Rust toolchain (install via rustup)
• Docker & Docker Compose
• .env file (copy from .env.example)

For detailed environment setup, see docs/development-setup.md

---

Quick Start

Note: .env.example includes a demo JWT_SECRET. For production, generate a secure secret (see Prerequisites).

# Copy example config
cp .env.example .env

# Start infrastructure (PostgreSQL + Redis)
docker compose up -d

# Run oauth2-server
cargo run -p oauth2-server

# Run oauth2-client (in another terminal)
cargo run -p oauth2-client

# Run jwt-service (in another terminal)
cargo run -p jwt-service

# Test endpoints:
#   OAuth2 client: http://localhost:8081
#   JWT health:    http://localhost:8083/health
#   OAuth2 server: http://localhost:8082 (API - see endpoints in logs)

---

Testing & Quality Assurance

Comprehensive automated test suite validating all authentication flows:

# Run complete JWT service test suite (10 automated tests)
./scripts/test-jwt-service.sh

What's tested:

• ✅ Token generation & validation (HS256 signing, expiration checking)
• ✅ Refresh token rotation (prevents replay attacks)
• ✅ Token revocation & blacklisting (Redis-backed)
• ✅ Protected route authentication (JWT middleware)
• ✅ Unauthorized access prevention (401 responses)
• ✅ Security edge cases (missing tokens, revoked tokens)

Test output example:

🧪 Testing JWT Service
...
✓ Token generation
✓ Token validation (valid)
✓ Token validation (invalid)
✓ Refresh token flow
✓ Refresh token rotation
✓ Token revocation
✓ Revoked token validation
✓ Protected route (valid token)
✓ Protected route (no token)
✓ Protected route (revoked token)
🎉 All JWT service tests passed!

Additional testing:

# Run all workspace tests
./scripts/test-all.sh

# Run local CI pipeline (format, clippy, tests)
./scripts/ci-local.sh

Quality metrics:

• 10 automated integration tests
• CI/CD pipeline validation
• Code formatting (cargo fmt)
• Linting (cargo clippy)
• Security-focused test scenarios

See scripts/test-jwt-service.sh for complete test implementation.

---

Development

See docs/development-setup.md for:

• Environment setup and configuration
• Running tests and local CI
• Code quality checks
• Development workflow
• Troubleshooting

Individual service documentation:

• oauth2-client/README.md - OAuth2 client implementation
• oauth2-server/README.md - Authorization server with database
• jwt-service/README.md - JWT token service with middleware

Contributing:

• CONTRIBUTING.md - Code style, documentation standards, architecture guidelines

---

Architecture

Built following Clean Architecture and EMBP (Explicit Module Boundary Pattern).

Key patterns:

• Explicit module boundaries via gateway files (mod.rs, lib.rs)
• Trait-based abstractions for business logic
• Comprehensive rustdoc with RFC references
• Security-first design (token rotation, revocation, middleware)

Code quality:

• Automated test coverage for critical paths
• RFC-compliant implementations (OAuth2 RFC 6749, JWT RFC 7519)
• Production-ready error handling
• Logging and observability

See EMBP documentation for architectural details.

---

License

MIT