Auth Framework

A comprehensive authentication and authorization framework for Rust applications.

Features

• Multiple Authentication Methods: OAuth, JWT, API keys, password-based authentication
• Token Management: Issuance, validation, refresh, and revocation
• Permission System: Role-based access control with fine-grained permissions
• Multi-Factor Authentication: Support for TOTP, SMS, email, and hardware keys
• Session Management: Secure session handling with expiration
• Rate Limiting: Built-in protection against brute force attacks
• Audit Logging: Comprehensive logging of authentication events
• Storage Backends: In-memory, Redis, PostgreSQL, MySQL support
• Middleware: Easy integration with web frameworks
• Distributed: Cross-node authentication validation

Quick Start

Add this to your Cargo.toml:

[dependencies]

auth-framework = "0.1.0"

tokio = { version = "1.0", features = ["full"] }

Basic Usage

use auth_framework::{AuthFramework, AuthConfig};
use auth_framework::methods::JwtMethod;
use auth_framework::storage::MemoryStorage;
use std::time::Duration;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure the auth framework
    let config = AuthConfig::new()
        .token_lifetime(Duration::from_secs(3600))
        .refresh_token_lifetime(Duration::from_secs(86400 * 7));
    
    // Create storage
    let storage = Arc::new(MemoryStorage::new());
    
    // Create the auth framework
    let mut auth = AuthFramework::new(config, storage);
    
    // Register a JWT authentication method
    let jwt_method = JwtMethod::new()
        .secret_key("your-secret-key")
        .issuer("your-service");
    
    auth.register_method("jwt", Box::new(jwt_method));
    
    // Initialize the framework
    auth.initialize().await?;
    
    // Create a JWT token for testing
    let token = auth.create_auth_token(
        "user123",
        vec!["read".to_string(), "write".to_string()],
        "jwt",
        None,
    ).await?;
    
    // Validate the token
    if auth.validate_token(&token).await? {
        println!("Token is valid!");
        
        // Check permissions
        if auth.check_permission(&token, "read", "documents").await? {
            println!("User has permission to read documents");
        }
    }
    
    Ok(())
}

OAuth Authentication

use auth_framework::methods::OAuth2Method;
use auth_framework::providers::OAuthProvider;

// Set up OAuth with GitHub
let oauth_method = OAuth2Method::new()
    .provider(OAuthProvider::GitHub)
    .client_id("your-github-client-id")
    .client_secret("your-github-client-secret")
    .redirect_uri("https://your-app.com/auth/callback");

auth.register_method("github", Box::new(oauth_method));

// Generate authorization URL
let (auth_url, state, pkce) = oauth_method.authorization_url()?;
println!("Visit: {}", auth_url);

// After user authorizes, exchange code for token
let credential = auth_framework::credentials::Credential::oauth_code("authorization-code-from-callback");
let result = auth.authenticate("github", credential).await?;

match result {
    auth_framework::AuthResult::Success(token) => {
        println!("GitHub authentication successful!");
        let user_info = auth.get_user_info(&token).await?;
        println!("Welcome, {}!", user_info.name.unwrap_or("User".to_string()));
    }
    _ => println!("Authentication failed"),
}

API Key Authentication

use auth_framework::methods::ApiKeyMethod;

// Set up API key authentication
let api_key_method = ApiKeyMethod::new()
    .key_prefix("ak_")
    .header_name("X-API-Key");

auth.register_method("api-key", Box::new(api_key_method));

// Create an API key for a user
let api_key = auth.create_api_key("user123", Some(Duration::from_secs(86400 * 30))).await?;
println!("New API key: {}", api_key);

// Authenticate with API key
let credential = auth_framework::credentials::Credential::api_key(&api_key);
let result = auth.authenticate("api-key", credential).await?;

Multi-Factor Authentication

// Enable MFA in configuration
let config = AuthConfig::new()
    .enable_multi_factor(true);

// Authentication with MFA
let credential = auth_framework::credentials::Credential::password("username", "password");
let result = auth.authenticate("password", credential).await?;

match result {
    auth_framework::AuthResult::MfaRequired(challenge) => {
        println!("MFA required. Challenge ID: {}", challenge.id());
        
        // User provides MFA code
        let mfa_code = "123456";
        let token = auth.complete_mfa(challenge, mfa_code).await?;
        println!("MFA successful!");
    }
    auth_framework::AuthResult::Success(token) => {
        println!("Direct authentication successful!");
    }
    auth_framework::AuthResult::Failure(reason) => {
        println!("Authentication failed: {}", reason);
    }
}

Permission Management

use auth_framework::permissions::{Permission, Role, PermissionChecker};

// Permission checking is built into the AuthFramework
// Create a test token first
let token = auth.create_auth_token(
    "user123",
    vec!["read".to_string(), "write".to_string()],
    "jwt",
    None,
).await?;

// Check permissions
let can_read = auth.check_permission(&token, "read", "documents").await?;
let can_write = auth.check_permission(&token, "write", "documents").await?;
let can_delete = auth.check_permission(&token, "delete", "documents").await?;

println!("Can read: {}, Can write: {}, Can delete: {}", can_read, can_write, can_delete);

Storage Configuration

Redis Storage

use auth_framework::config::{AuthConfig, StorageConfig};

let config = AuthConfig::new()
    .storage(StorageConfig::Redis {
        url: "redis://localhost:6379".to_string(),
        key_prefix: "auth:".to_string(),
    });

Custom Storage

use auth_framework::storage::AuthStorage;
use auth_framework::tokens::AuthToken;

#[derive(Clone)]
struct MyCustomStorage;

#[async_trait::async_trait]
impl AuthStorage for MyCustomStorage {
    async fn store_token(&self, token: &AuthToken) -> Result<()> {
        // Your custom storage implementation
        Ok(())
    }
    
    async fn get_token(&self, token_id: &str) -> Result<Option<AuthToken>> {
        // Your implementation
        Ok(None)
    }
    
    async fn delete_token(&self, token_id: &str) -> Result<()> {
        // Your implementation
        Ok(())
    }
    
    // Implement other required methods...
}

// Use your custom storage
let storage = Arc::new(MyCustomStorage);
let auth = AuthFramework::new(config, storage);

Rate Limiting

use auth_framework::config::RateLimitConfig;

let config = AuthConfig::new()
    .rate_limiting(RateLimitConfig::new(
        100, // max requests
        Duration::from_secs(60), // per minute
    ));

Middleware Integration

Axum Integration

use axum::{
    extract::{Request, State},
    http::StatusCode,
    middleware::Next,
    response::Response,
};

async fn auth_middleware(
    State(auth): State<Arc<AuthFramework>>,
    mut request: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    let auth_header = request.headers()
        .get("Authorization")
        .and_then(|h| h.to_str().ok())
        .and_then(|s| s.strip_prefix("Bearer "));
    
    if let Some(token_str) = auth_header {
        // In a real implementation, you'd need to parse the token string back to AuthToken
        // This is simplified for demonstration
        if token_str.starts_with("valid_") {
            return Ok(next.run(request).await);
        }
    }
    
    Err(StatusCode::UNAUTHORIZED)
}

Actix Web Integration

use actix_web::{dev::ServiceRequest, Error, HttpMessage};
use actix_web_httpauth::extractors::bearer::BearerAuth;

async fn auth_validator(
    req: ServiceRequest,
    credentials: BearerAuth,
) -> Result<ServiceRequest, Error> {
    let auth = req.app_data::<web::Data<AuthFramework>>().unwrap();
    
    if let Ok(Some(token)) = auth.storage.get_token_by_access_token(credentials.token()).await {
        if auth.validate_token(&token).await.unwrap_or(false) {
            req.extensions_mut().insert(token);
            return Ok(req);
        }
    }
    
    Err(AuthError::auth_method("bearer", "Invalid token").into())
}

Configuration

Full Configuration Example

use auth_framework::config::*;

let config = AuthConfig::new()
    .token_lifetime(Duration::from_secs(3600))
    .refresh_token_lifetime(Duration::from_secs(86400 * 7))
    .enable_multi_factor(true)
    .storage(StorageConfig::Redis {
        url: "redis://localhost:6379".to_string(),
        key_prefix: "auth:".to_string(),
    })
    .rate_limiting(RateLimitConfig::new(100, Duration::from_secs(60)))
    .security(SecurityConfig::secure())
    .audit(AuditConfig {
        enabled: true,
        log_success: true,
        log_failures: true,
        log_permissions: true,
        log_tokens: false,
        storage: AuditStorage::Tracing,
    });

Security Considerations

1. Secret Management: Never hardcode secrets. Use environment variables or secure vaults.
2. Token Storage: Use secure storage backends in production (Redis, PostgreSQL).
3. HTTPS: Always use HTTPS in production to protect tokens in transit.
4. Rate Limiting: Enable rate limiting to prevent brute force attacks.
5. Token Expiration: Set appropriate token lifetimes based on your security requirements.
6. Audit Logging: Enable comprehensive audit logging for security monitoring.

Examples

See the examples/ directory for complete examples:

• basic.rs - Basic authentication setup (working)
• oauth.rs - OAuth integration (working)

Additional examples (currently being updated):

• api_keys.rs - API key management
• mfa.rs - Multi-factor authentication
• permissions.rs - Advanced permission management
• middleware.rs - Web framework integration
• benchmarks.rs - Performance benchmarks
• security_audit.rs - Security features demonstration

Note: Some examples are currently being updated to match the latest API. The basic.rs and oauth.rs examples are fully functional.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our development process, coding standards, and how to submit pull requests.

Security

Security is our top priority. Please review our Security Policy for:

• Reporting security vulnerabilities
• Security best practices
• Supported versions
• Compliance information

For security issues, please email security@example.com instead of using the issue tracker.

License

This project is licensed under the MIT OR Apache-2.0 license.