Rust OAuth2 Server¶

Welcome to the comprehensive documentation for the Rust OAuth2 Server - a production-ready, high-performance OAuth2 authorization server built with Rust and Actix-web.

🌟 What is Rust OAuth2 Server?¶

The Rust OAuth2 Server is a complete OAuth2 implementation designed for modern cloud-native applications. It combines Rust's safety guarantees with the actor model for concurrent, fault-tolerant authentication and authorization services.

🚀 Features¶

• ✅ Complete OAuth2 implementation with all standard flows
• 🎭 Actor model for concurrent request handling
• 🔒 Type-safe Rust implementation
• 📊 Prometheus metrics and OpenTelemetry tracing
• 📚 OpenAPI documentation with Swagger UI
• 🎨 Admin control panel
• 🗄️ Flyway database migrations
• 🐳 Docker and Kubernetes ready

Architecture Overview¶

OAuth2 Flows Supported¶

1. Authorization Code Flow (with PKCE)¶

The most secure flow for web and mobile applications:

When to use: Web applications, mobile apps, SPAs

Learn more →

2. Client Credentials Flow¶

For service-to-service authentication:

When to use: Microservices, backend services, APIs

Learn more →

3. Refresh Token Flow¶

Obtain new access tokens without re-authentication:

When to use: Extending user sessions, mobile apps

Learn more →

4. Password Grant Flow¶

Learn more →

Quick Start¶

1. Install and Setup¶

# Clone the repository
git clone https://github.com/ianlintner/rust_oauth2_server.git
cd rust_oauth2_server

# Run database migrations
./scripts/migrate.sh

# Start the server
cargo run

2. Register Your First Client¶

curl -X POST http://localhost:8080/clients/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["http://localhost:3000/callback"],
    "grant_types": ["authorization_code"],
    "scope": "read write"
  }'

3. Get Access Token¶

# Client credentials flow example
curl -X POST http://localhost:8080/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Documentation Structure¶

Getting Started¶

• Installation - Set up the OAuth2 server
• Quick Start - Your first OAuth2 flow
• Configuration - Complete configuration guide
• Social Login Setup - Configure social providers

Architecture¶

• Overview - System architecture and design
• Actor Model - Actor-based concurrency
• Database - Schema and data access patterns

OAuth2 Flows¶

• Authorization Code - Standard authorization flow
• Client Credentials - Service-to-service auth
• Refresh Token - Token refresh mechanism
• Password Grant - Resource owner password credentials

API Reference¶

• Endpoints - Complete API documentation
• Authentication - Token usage and scopes
• Error Handling - Error responses and codes

Observability¶

• Metrics - Prometheus metrics
• Tracing - OpenTelemetry tracing
• Logging - Structured logging
• Health Checks - Health and readiness endpoints

Admin Panel¶

• Dashboard - Admin web interface
• Client Management - Managing OAuth2 clients
• Token Management - Token administration

Deployment¶

• Docker - Container deployment
• Kubernetes - K8s manifests
• Production - Best practices and security

Development¶

• Contributing - How to contribute
• Testing - Testing guide
• CI/CD - Continuous integration

Key Features¶

🔒 Security First¶

• PKCE support for public clients
• Secure token storage with hashing
• Scope-based authorization
• Token revocation support
• CSRF protection
• Rate limiting (planned)

⚡ High Performance¶

• Async I/O with Tokio
• Actor-based concurrency
• Connection pooling
• Efficient request handling
• Minimal memory footprint

📊 Observable¶

• Prometheus metrics
• OpenTelemetry tracing
• Structured JSON logging
• Health check endpoints
• Admin dashboard

🌐 Cloud Native¶

• Stateless design
• Docker container support
• Kubernetes ready
• Horizontal scaling
• Zero-downtime deployments

Example Usage¶

Register a Client¶

curl -X POST http://localhost:8080/clients/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Application",
    "redirect_uris": ["http://localhost:3000/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "scope": "read write"
  }'

Get Access Token¶

curl -X POST http://localhost:8080/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Use Access Token¶

curl http://your-api.com/protected/resource \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Monitoring¶

Access the admin dashboard at http://localhost:8080/admin to view:

• Active tokens and clients
• Request metrics and latency
• System health status
• Recent activity logs

View Prometheus metrics at http://localhost:8080/metrics

View Swagger UI at http://localhost:8080/swagger-ui

Support and Community¶

• Documentation: You're reading it!
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Source Code: GitHub Repository

Next Steps¶

1. Install the server - Get up and running
2. Follow the quick start - Complete your first flow
3. Explore OAuth2 flows - Understand the protocols
4. Configure for production - Deploy securely
5. Set up monitoring - Track performance

License¶

This project is dual-licensed under MIT OR Apache-2.0.

Ready to get started? Head over to the Installation Guide!