Configuration Guide¶

This comprehensive guide covers all configuration options available for the Rust OAuth2 Server.

Configuration Methods¶

The server supports multiple configuration methods:

1. Environment Variables (Recommended for production)
2. .env File (Recommended for development)
3. Configuration File (Alternative method)

Environment Variables¶

All configuration options can be set via environment variables with the OAUTH2_ prefix.

Server Configuration¶

Example:

export OAUTH2_SERVER_HOST=0.0.0.0
export OAUTH2_SERVER_PORT=8080
export OAUTH2_SERVER_WORKERS=4

Database Configuration¶

Supported Databases:

export OAUTH2_DATABASE_URL=sqlite:oauth2.db
# Or with absolute path
export OAUTH2_DATABASE_URL=sqlite:/path/to/oauth2.db

export OAUTH2_DATABASE_URL=postgresql://username:password@localhost:5432/oauth2_db
# With SSL
export OAUTH2_DATABASE_URL=postgresql://username:password@localhost:5432/oauth2_db?sslmode=require

# Local MongoDB
export OAUTH2_DATABASE_URL=mongodb://localhost:27017/oauth2

# MongoDB Atlas (SRV)
export OAUTH2_DATABASE_URL=mongodb+srv://user:pass@cluster0.example.mongodb.net/oauth2

JWT Configuration¶

Generating a secure JWT secret:

# Using openssl
openssl rand -hex 32

# Using /dev/urandom
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1

Example:

export OAUTH2_JWT_SECRET="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

Token Expiration¶

Example:

# Access token valid for 1 hour
export OAUTH2_ACCESS_TOKEN_EXPIRATION=3600

# Refresh token valid for 30 days
export OAUTH2_REFRESH_TOKEN_EXPIRATION=2592000

# Authorization code valid for 10 minutes
export OAUTH2_AUTHORIZATION_CODE_EXPIRATION=600

Session Configuration¶

Example:

export OAUTH2_SESSION_KEY="your-persistent-session-key-at-least-64-characters-long-abc123"
export OAUTH2_SESSION_TIMEOUT=7200
export OAUTH2_SESSION_SECURE=true

Social Login Configuration¶

Google OAuth2¶

Microsoft/Azure AD¶

GitHub¶

Okta¶

Auth0¶

Complete Social Login Example:

# Google
export OAUTH2_GOOGLE_CLIENT_ID="123456-abc.apps.googleusercontent.com"
export OAUTH2_GOOGLE_CLIENT_SECRET="GOCSPX-abc123def456"
export OAUTH2_GOOGLE_REDIRECT_URI="http://localhost:8080/auth/callback/google"

# Microsoft
export OAUTH2_MICROSOFT_CLIENT_ID="12345678-1234-1234-1234-123456789abc"
export OAUTH2_MICROSOFT_CLIENT_SECRET="abc~123.def456"
export OAUTH2_MICROSOFT_REDIRECT_URI="http://localhost:8080/auth/callback/microsoft"
export OAUTH2_MICROSOFT_TENANT_ID="common"

# GitHub
export OAUTH2_GITHUB_CLIENT_ID="Iv1.a1b2c3d4e5f6g7h8"
export OAUTH2_GITHUB_CLIENT_SECRET="1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t"
export OAUTH2_GITHUB_REDIRECT_URI="http://localhost:8080/auth/callback/github"

See Social Login Setup Guide for detailed provider configuration.

OpenTelemetry Configuration¶

Example:

export OAUTH2_OTLP_ENDPOINT=http://jaeger:4317
export OAUTH2_OTLP_PROTOCOL=grpc
export OAUTH2_OTLP_TRACES_ENABLED=true

Logging Configuration¶

Log Levels:

• error - Error messages only
• warn - Warnings and errors
• info - Informational messages (recommended)
• debug - Debug information
• trace - Very verbose logging

Example:

# Production: JSON formatted info logs
export RUST_LOG=info
export OAUTH2_LOG_FORMAT=json

# Development: Pretty printed debug logs
export RUST_LOG=debug,sqlx=warn
export OAUTH2_LOG_FORMAT=pretty

CORS Configuration¶

Example:

export OAUTH2_CORS_ALLOWED_ORIGINS="https://app.example.com,https://admin.example.com"
export OAUTH2_CORS_ALLOWED_METHODS="GET,POST,OPTIONS"
export OAUTH2_CORS_MAX_AGE=7200

Configuration File Example¶

Create a complete .env file for your environment:

Development Configuration¶

# .env.development
# Server
OAUTH2_SERVER_HOST=127.0.0.1
OAUTH2_SERVER_PORT=8080

# Database
OAUTH2_DATABASE_URL=sqlite:oauth2.db

# JWT
OAUTH2_JWT_SECRET=dev-secret-key-change-in-production-minimum-32-chars

# Session
OAUTH2_SESSION_KEY=dev-session-key-must-be-at-least-64-characters-for-security-123456

# Tokens
OAUTH2_ACCESS_TOKEN_EXPIRATION=3600
OAUTH2_REFRESH_TOKEN_EXPIRATION=2592000

# Logging
RUST_LOG=debug,sqlx=warn
OAUTH2_LOG_FORMAT=pretty

# OpenTelemetry
OAUTH2_OTLP_ENDPOINT=http://localhost:4317

Production Configuration¶

# .env.production
# Server
OAUTH2_SERVER_HOST=0.0.0.0
OAUTH2_SERVER_PORT=8080
OAUTH2_SERVER_WORKERS=8

# Database (PostgreSQL)
OAUTH2_DATABASE_URL=postgresql://oauth2_user:strong_password@postgres:5432/oauth2_db?sslmode=require
OAUTH2_DATABASE_MAX_CONNECTIONS=20
OAUTH2_DATABASE_MIN_CONNECTIONS=5

# JWT (Use secret management service)
OAUTH2_JWT_SECRET=${SECRET_JWT_KEY}

# Session (Use secret management service)
OAUTH2_SESSION_KEY=${SECRET_SESSION_KEY}
OAUTH2_SESSION_TIMEOUT=7200
OAUTH2_SESSION_SECURE=true

# Tokens
OAUTH2_ACCESS_TOKEN_EXPIRATION=1800
OAUTH2_REFRESH_TOKEN_EXPIRATION=604800

# Logging
RUST_LOG=info,actix_web=warn
OAUTH2_LOG_FORMAT=json

# OpenTelemetry
OAUTH2_OTLP_ENDPOINT=http://otel-collector:4317

# CORS
OAUTH2_CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
OAUTH2_CORS_MAX_AGE=7200

# Social Login (from secret management)
OAUTH2_GOOGLE_CLIENT_ID=${SECRET_GOOGLE_CLIENT_ID}
OAUTH2_GOOGLE_CLIENT_SECRET=${SECRET_GOOGLE_CLIENT_SECRET}
OAUTH2_GOOGLE_REDIRECT_URI=https://oauth.example.com/auth/callback/google

Docker Configuration¶

Using Environment Variables¶

# docker-compose.yml
version: '3.8'

services:
  oauth2_server:
    image: rust_oauth2_server:latest
    ports:
      - "8080:8080"
    environment:
      OAUTH2_SERVER_HOST: 0.0.0.0
      OAUTH2_SERVER_PORT: 8080
      OAUTH2_DATABASE_URL: postgresql://oauth2:password@postgres:5432/oauth2_db
      OAUTH2_JWT_SECRET: ${JWT_SECRET}
      OAUTH2_SESSION_KEY: ${SESSION_KEY}
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: oauth2_db
      POSTGRES_USER: oauth2
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Using .env File¶

# docker-compose.yml
version: '3.8'

services:
  oauth2_server:
    image: rust_oauth2_server:latest
    ports:
      - "8080:8080"
    env_file:
      - .env.production

Kubernetes Configuration¶

ConfigMap¶

apiVersion: v1
kind: ConfigMap
metadata:
  name: oauth2-config
data:
  OAUTH2_SERVER_HOST: "0.0.0.0"
  OAUTH2_SERVER_PORT: "8080"
  OAUTH2_DATABASE_URL: "postgresql://oauth2:password@postgres:5432/oauth2_db"
  OAUTH2_LOG_FORMAT: "json"
  RUST_LOG: "info"

Secret¶

apiVersion: v1
kind: Secret
metadata:
  name: oauth2-secrets
type: Opaque
stringData:
  OAUTH2_JWT_SECRET: "your-jwt-secret-here"
  OAUTH2_SESSION_KEY: "your-session-key-here"
  OAUTH2_GOOGLE_CLIENT_SECRET: "google-secret-here"

Deployment¶

apiVersion: apps/v1
kind: Deployment
metadata:
  name: oauth2-server
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: oauth2-server
        image: rust_oauth2_server:latest
        envFrom:
        - configMapRef:
            name: oauth2-config
        - secretRef:
            name: oauth2-secrets
        ports:
        - containerPort: 8080

Configuration Validation¶

The server validates critical configuration at startup:

Production Checklist¶

The server warns if production requirements aren't met:

• ✅ JWT secret is at least 32 characters
• ✅ Session key is at least 64 characters
• ✅ Database URL is configured
• ✅ HTTPS is enabled for sessions (in production)
• ✅ Secure cookie settings are enabled

View validation results:

# Start server and check logs
cargo run 2>&1 | grep -i "configuration\|warning"

Advanced Configuration¶

Custom Token Claims¶

Customize JWT token claims by modifying the configuration:

export OAUTH2_JWT_ISSUER=https://oauth.example.com
export OAUTH2_JWT_AUDIENCE=https://api.example.com

Database Connection Pooling¶

Fine-tune database performance:

export OAUTH2_DATABASE_MAX_CONNECTIONS=50
export OAUTH2_DATABASE_MIN_CONNECTIONS=10
export OAUTH2_DATABASE_CONNECT_TIMEOUT=30
export OAUTH2_DATABASE_IDLE_TIMEOUT=600

Rate Limiting (Planned)¶

export OAUTH2_RATE_LIMIT_ENABLED=true
export OAUTH2_RATE_LIMIT_REQUESTS_PER_MINUTE=60
export OAUTH2_RATE_LIMIT_BURST=10

Troubleshooting¶

Configuration Not Loading¶

1. Check environment variable names (must start with OAUTH2_)
2. Verify .env file is in the correct directory
3. Check for syntax errors in .env file
4. Ensure no spaces around = in .env file

Database Connection Failures¶

1. Verify database URL format
2. Check network connectivity
3. Verify credentials
4. Check firewall rules

JWT Token Issues¶

1. Ensure JWT secret is set and long enough
2. Verify secret hasn't changed (invalidates existing tokens)
3. Check token expiration settings

Best Practices¶

1. Never commit secrets to version control
2. Use .gitignore for .env files

3. Use secret management services in production

4. Use strong secrets

5. Generate cryptographically random secrets
6. Use minimum recommended lengths

7. Rotate secrets periodically

8. Environment-specific configuration

9. Separate dev, staging, and production configs
10. Use different secrets for each environment

11. Document required variables

12. Database configuration

13. Use PostgreSQL in production
14. Configure appropriate connection pools

15. Enable SSL for database connections

16. Monitoring and logging

17. Use JSON logs in production
18. Configure appropriate log levels
19. Enable OpenTelemetry tracing

Next Steps¶

• Quick Start Guide - Start using the OAuth2 server
• Social Login Setup - Configure social providers
• Production Deployment - Deploy to production
• Security Best Practices - Secure your deployment